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INTRODUCTION 

This document explains how to use the 5.2 release of the Operating System. 
It includes all relevant material from prior releases and also describes 
the new features of this release. The User's Guide does not explain each 
feature of the OS in detail; instead, it explains operations such as 
installing and booting the system, and presents the details of the Command 
Shell and Filer commands (see the Operating System Reference Manual for a 
complete description of the Operating system). 

Because the Operating System Reference Manual is not updated for each new 
release, the User's Guide also contains explanations of any new features or 
calls that may not fit into the above topics • The User's Guide assumes 
that the Operating System Reference Manual that you have is dated March 1, 
1982. 

This release of the Operating System boots from a Profile or Twiggy rather 
than the Apple II. The standalone OS is installed and operates differently 
than the OS that boots from the Apple in several ways. Please read the 
paragraphs below that explain the environment that this version of the OS 
supports before attempting to install and run it. 



CONFIGURATION 

The standalone OS boots from either a Profile or a Twiggy. Most people 
will boot the standalone OS from a Profile, and use another hard disk for 
the Monitor. 

The standalone OS restricts how you can use the various devices. The OS 
treats the Corvus as a source of Monitor files, not as an OS volume; the 
Apple, the Disk-II floppies and the Sanyo screen are totally inaccessible 
from the OS; the Lisa screen and keyboard are reserved for Applications. 
Therefore, read Ins and writelns can only be seen on your Soroc. 

WARNING: YOU NEED A SOROC, TO USE THE STANDALONE OS! Attach the Soroc to 
channel A of the Lisa; this channel is the second from the left when you 
are standing in front of the system. 

When the OS boots from a Profile, that Profile must be attached to the 
parallel port (the connector farthest to the right when viewed from the 
front). This port is 'PARAPORT' to the OS and '&3' to the Monitor. 

Your other hard disks are attached to the N-Port card, which must (for now) 
be in Slot 2 (the middle slot). Starting from the bottom of the N-Port 
card, the ports are named '&4', '&5', and '&6' by the monitor, and 
'SL0T2CHAN1', ' SLOT2CHAN2 ' , and 'SLOT2CHAN3' by the OS. The monitor gives 
preference to disks attached to the bottom of the N-Port card, so your 
monitor disk should probably be attached to &4. 
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Before installing the OS, you must run the OSCONFIG program under the 
Monitor. OSCONFIG produces a configuration file that defines, at boot 
time, which devices are attached at each port (&3 thru &6), and which ONE 
disk is the Monitor's working device, the device theOS can access Monitor 
files from. OSCONFIG also allows you to emulate a smaller machine. 

The devices OSCONFIG recognizes are Profile, Corvus, and printers. If a 
device isn't named in the configuration program, the OS doesn't see it even 
if you explicitly mount it. To change your configuration, rerun OSCONFIG 
under the Monitor, FTP the new configuration file into the OS as 
SYSTEM. CONFIG, shutdown the OS, physically switch to the new arrangement, 
and then reboot the OS. If your boot volume contains no SYSTEM. CONFIG 
file, the only device configured is the disk you are booting. 



OS VOLUME TYPES 

The OS currently supports two types of file system volumes, one built on 
top of the Monitor's concept of logical volumes and one entirely 
independent of Monitor volumes. The type of OS file system volume built 
within a Monitor logical volume is what you've used for the last few months 
when running the OS under the Monitor on a single disk. 

Under the current OS, you can only access this type of volume on the 

designated Monitor working device. This type of OS volume CANNOT be a boot 

volume. It can reside anywhere on the disk and its access is totally 
protected by the Monitor's mount table. 

'OS Devices' is the term used to describe the second type of volume. This 
type of volume CAN be a boot volume. However, an OS device has only a 
single OS volume that must start at the beginning of the device. When you 
initialize that volume, you specify how many blocks (pages) are it has. 

The OS initializes the specified number of pages on the OS device. For 
example, if you specify 9720 blocks when initializing a Profile as an OS 
device, all 9720 blocks are rewritten from the front of the disk without 
regard for any Monitor volumes that already exist there. The OS doesn't 
check the mount table to avoid destruction of existing Monitor volumes. 

However, it is possible for a device to be both an OS and a Monitor device 
if you create the Monitor volumes BEYOND the portion of the disk used as 
the OS volume. To reserve room for the OS volume, create a Monitor volume 
(under the volume manager) starting at the first physical block (block 8) 
of the disk that has the same size as the number of blocks you need for the 
OS device. The remaining space is usable for other Monitor volumes. 

WARNING: When initializing an OS device that is split between an OS volume 
and Monitor volumes, be sure to initialize the correct number of pages. 
Specifying too large a number of blocks results in the destruction of 
Monitor volumes that follow the OS volume. In general, BE CAREFUL when 
mixing OS volumes and Monitor volumes on one device. 
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SYSTEM FILES 

The standalone OS is distributed on a Profile that holds a bootable copy of 
the OS, miscellaneous release files, and the installation utilities. The 
files below define the release. All files listed, except OSCONFIG and 
OSINSTALL, should be on the OS boot volume. All are required to boot and 
run the OS except for RS232TEST. 



SYSTEM. OS - The main portion of the OS code. 

SYSTEM. SHELL - OS command shell 

SYSTEM. BT_PROF - The profile version of the OS loader 

SYSTEM. BTJTWIG - The Twiggy version of the OS loader 

SYSTEM. DEBUG - First part of Lisabug 

SYSTEM. DEBUG2 - Second part of Lisabug 

SYSTEM.LLD - Low level drivers 

SYSTEM. CONFIG - User-produced definition of desired configuration 

IOSPASLIB.OBJ - System runtime library 

INTRINSIC. LIB - Intrinsic unit directory 

RS232TEST - RS232 test program (optional) 

OSINSTALL. TEXT - Exec file that transfers files onto your OS volume 

OSCONFIG - Monitor-based utility to generate a SYSTEM. CONFIG 
file 

The files in the following list may be useful to you, but are not required 
to install the OS. 

SYSCALL.OBJ - Public system calls unit 

PSYSCALL.OBJ - Privileged system calls unit 
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INSTALLING THE OS 

The following are the steps required to install OS 5.2 onto a Profile: 

1) Attach the library OS Profile to &3, the parallel port of your 
system, attach your target OS boot Profile to &5, the port on 
the N-port card that is second from the bottom, and attach the 
source of the Monitor's root volume (ie, #5:) at &4, the bottom 
port of the N-port card. 

2) Boot the Monitor and make sure that the library Profile containing 
this version of the OS contains all the files listed above. 

3) Be sure the Sysmgr 'Zero' has been run at some time on your 
target OS boot Profile. OS devices need to have a valid volume 
table, both to avoid confusion when examining the drive from the 
Monitor, and to allow the OS to use the drive as the Monitor's 
working device if necessary. 

4) If you are developing programs on the Monitor to run on the OS, you 
have to transfer the following files from the library profile to a 
Monitor volume: 

OS52:IOSPASLIB.OBJ 
OS52: INTRINSIC. LIB 
OS52:SYSCALL.OBJ 
0S52:PSYSCALL.0BJ 

Also transfer 

OS52:OSCONFIG 

to a Monitor volume so that you can change configurations later. 

5) Run the OS52:OSCONFIG program to describe the configuration you 
want. The program expects single character numeric input. Save 
the configuration file in OS52: SYSTEM. CONFIG. 

6) Boot the library copy of the OS (see the section below on booting 
the OS for directions). 

7) Type 'P' to run the privileged filer and then type 'I' (for I(nit) 
to initialize your OS device (see the section on P(rivfiler if you 
need assistance). Use the name SLOT2CHAN2 to identify your profile 
at position &5. Depending on whether you have any Monitor volumes 
on your profile, you may want to respond with less than the maximum 
device size (9720) when I(nit asks how many pages (blocks) it should 
initialize for the OS volume. The OS uses 1300 blocks of your boot 
volume. So you will want to create at least 1500 blocks even if you 
don't intend to store anything else on the volume. Note that the OS 
boot volume must have enough space for the preallocated swap region, 
swap space for the applications, and swap space for data segments. 
Therefore, the minimum recommended size is 2000 blocks. 

Calvert 4 July 23, 1982 



Confidential Guide to OS 



8) Type 'Q' to return to the OS Shell. Then type 'F' to run the OS Filer. 
Once you are in the filer, type 'M' to mount your newly initialized 
profile using the name SLOT2CHAN2. The Mount command is described 
under the OS Filer. 

9) Type 'W to change your working directory to the name of your OS volume. 
If you don't change the working directory, the macro that transfers the 
system files to your OS boot volume will not run correctly. 

10) Type '0/ to return to the OS Shell. Once you are in the Shell, type 'X' 
to execute <OS52:OSINSTALL, a macro that transfers each of the following 
files into your initialized volume using the FTP utility 'T(rans': 

OS52: SYSTEM. OS 
OS52: SYSTEM. SHELL 
OS52 : SYSTEM. BTJ?R0F 
0S52 : SYSTEM. BTJTWIG 
OS52: SYSTEM. DEBUG 
OS52: SYSTEM. DEBUG2 
OS52: SYSTEM. LLD 
0S52: SYSTEM. CONFIG 
OS52:IOSPASLIB.OBJ 
0S52: INTRINSIC. LIB 
OS52:RS232TEST 

11) Quit the OS and wait for the system to reset itself. Then, detach 
the library Profile that contains the OS, and detach your Profile 
that contains the OS from the Lisa. Reconnect your OS standalone 
Profile at the parallel port, and attach all other devices comprising 
the configuration you stored in the configuration file. You should 
now be able to boot the OS from your Profile (see BOOTING below for 
instructions). 



Remember that the OS and UCSD file systems are not compatible. 
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HOW TO BOOT THE OS 

The boot prom can boot either the OS or the Monitor. To decide which 
system to boot and which device to boot from, the prom selects the FIRST of 
the following list of possibilities that it encounters: 

1. If one of the combinations of keys listed below is pressed at the 
right time, the prom selects the corresponding system/ boot device. 

'Command' followed by 'h' means boot the OS from the Profile 
on the parallel port 

'Command' followed by 'f ' means boot the OS from the top 
Twiggy drive 

'Command' followed by 'g' means boot the OS from the bottom 
Twiggy drive 

'Command' followed by 'm' means boot the Monitor from the Apple 
(for PROM 22) 

'Command' followed by 'a' means boot the Monitor from the Apple 
(for later PROMs) 

Learning the key press timing can be frustrating. The sweep pattern 
that appears about 3 or 4 seconds into the system power on process 
is your cue. Press and HOLD DOWN the command key after the sweep 
pattern appears, and then press the second key. You will probably 
make more mistakes by typing too soon than too late, so take your 
time. Within another 3 or 4 seconds either the 'BOOTING' message 
appears on the left of the screen (the prom saw the keys and is 
obeying) or the standard prom version display is seen (you'll have 
to try again). To try again, press the 'reset' button on the back 
of your machine, if you have one, or power your system off and back 
on. Pause at least 1 second between turning the machine on (in back) 
and pushing the 'power' button (in front). 

Version 102 or later of the boot prom makes a soft click instead of 
displaying the sweeping pattern when it's ready for you to type a boot 
device keycode, and a second click when it's no longer receptive. 

2. If parameter memory is 'valid', the prom uses the boot device stored 
there. Only version 102 of the prom stores a valid combination of 
boot keys in parameter memory. No other method of writing to parameter 
memory exists yet. 

3. Boot from the 'default' device. Currently, this means to boot the 
Monitor from the Apple. Some day, it will mean the top Twiggy. 



The Profile must be left on for each attempt to boot the OS. Hopefully, 
this won't endanger disk integrity. If you have a Corvus attached to the 
system, you may want to turn it off before powering the system off and on, 
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After booting the OS, the Soroc displays the OS version number, the devices 
in the current configuration, and the numbers of the available volumes. 
REMEMBER: only one Monitor file disk is accessible. 



SHUTTING DOWN THE OS 

Whenever a user process returns to the Shell, you can quit the OS. 
However, if a user-process exception or system exception occurs, special 
action is necessary to preserve the integrity of files. During the normal 
course of running the OS, user and system data destined for a disk volume 
may still be in memory. If you reset the machine and reboot while data is 
in the buffer, the disk will be in an inconsistent state. The table below 
describes several situations that cause this problem and recommends an 
action for each. 



Error 



Action 



Exception in USER process 
such as divide by zero, 
bus error, address error, 
etc. 

NMI in USER process that 
is indicated by entering 
debugger in a domain other 
than zero AND without 
the debugger condition 
'D0MAIN=2, OVERIDDEN TO 0' 



Type 'g' from the debugger 
and the OS continues to 
abort the process and do any 
necessary clean up work. 

Type 'g' from the debugger 
to continue executing the 
process. To abort the 
process, induce an arti- 
ficial exception. One way 
to do this is to set PC to 
Cpc 0') and then type 
'g'. The process will 
probably get an illegal 
instruction exception and 
the OS should be able to 
abort it and do any clean 
up work necessary. 
REMEMBER: this only works 
if the domain IS NOT ZERO. 



Exception in system 
code 



Once in the debugger, type 
'OSQUIT' from the debugger 
and the OS attempts to shut 
down the OS file system in 
an orderly fashion. You 
might have to type 'OSQUIT' 
several times before it 
works. DO NOT use NMI and 
'rb' to reset the machine 
unless OSQUIT does not work 
after repeated attempts. 
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NMI in system code Type 'g' to continue. To 

recover from a fatal error 
in the OS, type 'OSQUIT'. 
You may have to type 'OSQUIT' 
several times before it works 
DO NOT use NMI and 'rb' to 
reset the machine unless 
OSQUIT does not work after a 
dozen or so attempts. 



PROGRAM DEVELOPMENT 

To write a program that can run on the OS: 

1. On the Monitor: 

Compile your program using the SYSCALL unit 

Link the compiled version of your program with IOSPASLIB 

2. Boot the OS 

3. T(ransfer the linked .OBJ file to an OS file system volume 

4. X(ecute the program 
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THE OS COMMAND SHELL 

When the OS comes up, a system process (the Root process) looks on the OS 
volume for a program file named SYSTEM. SHELL, If the OS finds one, it uses 
it as the OS command shell. If the OS doesn't find a SYSTEM. SHELL file, 
the Root process complains and goes automatically to the file transfer 
utility. At this point you can transfer any file from the UCSD world to 
serve as the OS shell. When you leave the file transfer utility, the Root 
process again looks for SYSTEM. SHELL. It repeats this cycle until it 
finally finds and starts up a shell. 

To change the shell, kill the current SYSTEM. SHELL, transfer a new 
SYSTEM. SHELL to the OS volume, and then type '0/ to quit. The Q(uit 
command asks whether or not you want to restart the Shell. If you type 'n' 
or press the carriage return, the OS terminates the Shell and shuts down 
the system. If you type 'y' in response to the question, the OS recreates 
the Shell from SYSTEM. SHELL. This procedure assumes that your current 
shell can kill and transfer files. 

The position of a device determines its OS device name. The definitions of 
OS device names are as follows: 

-PARAPORT is the device attached to the parallel port. 

-SLOTxCHANy is the device attached to a 4-port card's slot x and 
channel y. Slots and channels are numbered 1, 2, and 3. Slot 1 
is the slot furthest from the power supply side of the machine; 
channel 1 is the bottom channel. EXAMPLE: A drive connected to 
the bottom port on a 4-port card that is in slot 2 is mounted as 
device -SL0T2CHAN1. 



The remainder of this section presents the OS Command Shell line and 
explains the OS command shell options. The OS command shell behaves like 
the UCSD command shell; to invoke an action, type the first character of 
the option you desire. 

lisaOS: X(ecute, D(ebug, F(iler, P(rivFiler, T(ime, V(ers, 0(ff, Q(uit 



X(ecute Executes a program. It prompts for the name of 
the program file to execute and expects the full 
OS file system name of a file that is on the OS 
volume. You must compile a program that runs on 
the OS with the SYSCALL unit and link it with 
IOSPASLIB before transferring it to the OS file 
system. If the character '<' precedes the file 
name, the Shell assumes that the file is an exec 
file. OS exec file format is the same as the 
Monitor format. The system determines which type 
of volume an exec file resides on by the file name 
used (see the T(rans command). 
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D(ebug 



Debugs a program. D(ebug acts the same as the 
X(ecute command except that the program comes up 
with a breakpoint at its first instruction. Due 
to the breakpoint, the system enters Lisabug and 
you can debug as usual. After prompting for the 
name of the program to debug, the command asks if 
you also want to debug all the son processes. If 
you type 'n' for no, only the process created to 
run the program comes up with the breakpoint at 
the first instruction. If you type 'y' for yes, 
every process created until the main program 
terminates comes up with a breakpoint on the first 
instruction. 



F(iler Enters the Filer (described below). 

P(rivFiler Enters the privileged Filer (described below). 

T(ime Displays the current date/time setting and lets you 

enter a new date and/or time if desired. Type <CR> 
to indicate no change. To change the date or time, 
enter the new date and/or time in the format that 
the prompt specifies. 



L(ib 



Re-installs the Intrinsic Unit Directory file in 
memory. The command assumes that the new 
INTRINSIC. LIB file is already on the OS volume 
and that the Shell is the only process running in 
the system. If any error occurs during directory 
installation, a system error results and you must 
restart the OS. You can transfer and use a new 
INTRINSIC. LIB and use it while the OS is rebooting. 
Usually, no problems should occur when installing 
a new directory. NOTE: you cannot change IOSPASLIB 
using this command; you must reboot the OS to change 
it. 



V(ers 



Lists module version numbers and the OS release 
number. The OS group uses it to determine which 
versions of the OS components are being used. 



0(ff 



Turns Lisa off. The user is warned that power is 

about to be turned off. Answering yes Cy' or 'Y') 

to the warning prompt terminates the Shell and turns 

off the Lisa. Any other answer returns to the Shell 
command line. 
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Q(uit 



Terminates the current Shell process. The user is 
asked if a new shell should be created or if the 
Operating System should be shut down and the Lisa 
reset (the power is left on). Note that the Q(uit 
and 0(ff commands are 



THE ACCEPTABLE WAYS TO LEAVE THE OS 
AND RETURN TO THE MONITOR. 

These alternatives allow the Operating System to 
completely close and flush files that are open 
and to put the disk in a consistent state. If you 
do not wish to shut down the the system, the OS 
tries to start another SYSTEM. SHELL program. Use 
this to change Shells while running under the OS. 
You can also type 'OSQUIT' to return to the Monitor. 
This alternative is not desirable but is encouraged 
if the other alternatives don't work. 



THE FILER 

There are two 'Filers' in the OS environment. The 'Filer' handles normal 
file operations. The 'PrivFiler' handles special privileged operations 
mostly used to manage volumes. 

When prompted for a device name, a response of <CR> is sufficient to 
specify the current working directory. In general, however, a response of 
<CR> to a prompt indicates that the command should be aborted. In those 
situations where <CR> means the current working directory, a response of 
<ESC> aborts the command. 

The first half of the Filer command line is: 

Filer: T(rans, L(ist, N(ew, K(ill, R(ename, M(ount, U(nmount, Q(uit, ? 

Note that '?' is a command, not a request for information. It causes the 
command prompt to flip to the other half of the command line and display 
the other available commands. The other half of the Filer command line is: 

W(orkingDir, S(afety, D(eleteFiles 

T(rans 

T(rans invokes the file transfer utility FTP. FTP transfers files from the 
Monitor to the OS and from OS files to other OS files. Give FTP the source 
file name using either the UCSD file name syntax or the OS file name 
syntax, depending on the file, and the destination file name using the OS 
syntax. If a file with the destination file name already exists, FTP asks 
you for confirmation before writing over the old file. Once the transfer 
is complete, FTP asks for the next file to transfer. Type <cr> to exit. 
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Because two different file naming conventions are in use here, perhaps an 
example will be useful: 

T(ransfer 

What Lisa or UCSD file to transfer? VOL : MYTEXT. TEXT <cr> 
What Lisa file to transfer into? -DISK-MYFILE <cr> 
What UCSD file to transfer? <cr> 



This example takes the Pascal text file MYTEXT. TEXT from the Pascal volume 
named VOL and places it in the Lisa file MYFILE that is on the Lisa volume 
named DISK. 

Note that Paslib now supports RESET/REWRITE to an OS file. Therefore the 
prompt for the name of the file to transfer accepts either an OS file name 
or a Monitor file name. 

Because Paslib supports both Monitor volumes and OS volumes, the following 
naming convention has been adopted in order to distinguish one type from 
the other. A file name represents a Monitor file only if a colon (:) is 
one of the characters in the name AND the leading character of the name is 
not a dash (-). So, for example, you can transfer an OS file named 
VOL: MYTEXT. TEXT as long as you add a dash to the beginning of the name. 
Note that even when you transfer a Monitor file that resides on the boot 
volume, you must type the volume number or name and the file name; typing 
only the file name is not sufficient to identify the file. 

T(rans currently can only transfer Monitor files that reside in one of the 
SHORT directory volumes on the Monitor working device. The command 
considers the large directory volumes on the Monitor device invalid and 
skips over them when searching the volume for the specified file. If you 
want to transfer a file that is currently in a large directory, create a 
short directory volume and transfer the necessary file or files to that 
directory while running under the Monitor. Then, boot the OS and transfer 
the files. The next release of the OS or Paslib will support large 
directory Monitor volumes . 

If you have multiple hard disks connected to your system via the 4-port 

card, you can only transfer the UCSD files stored on a single device. To 

select a working device you run the OSCONFIG program and copy the result 
into your OS boot volume. 

Note that the transfer utility does not recognize the new Monitor file name 
syntax (DEV/VOL: FILE). 

If you transfer a file into the Lisa file INTRINSIC. LIB, the system asks 
you if it should install the new Intrinsic Unit Directory immediately. The 
system installs it if you respond 'Y' or 'y'. If you choose not to install 
the new directory at that time, you must use the L(ib command later to 
install it yourself before running any programs that use the new 
INTRINSIC. LIB file. 
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L(ist 

Lists the files on a given directory, their sizes and the disk space that 
each uses. The disk space size is the number of blocks (512 bytes) 
currently allocated to the file (the PEOF), whereas the file size is the 
number of bytes of data in the file (the LEOF). 



N(ew 
Creates a new file. 



K(ill 



Deletes a file. 



R(ename 

Renames an existing file or volume. If a volume is renamed, you must 
precede the volume name with a dash. Do not specify the dash if you are 
renaming a file on the working directory. 

M(ount 
U(nmount 

The two commands permit you to manage multiple OS file system volumes. 



S(afety 

Toggles the safety switch of a file on or off. The command asks for a file 
name and then asks whether the switch should be turned on (respond 'y' to 
the question) or off (respond 'n' or just <CR>). 



W(orkingDir 

Displays the current working directory and then prompts for a new one. To 
change it, type the name of the new working directory; <CR> indicates no 
change. When changing the working directory, use a complete volume name 
(remember to include the '-') or the command has no effect. '-DEV9' and 
'-MyVol' are two example volume names. Once a working directory is set, 
partially specified pathnames are evaluated using that directory. If you 
UNMOUNT the volume containing the current working directory, the boot 
volume becomes the working directory. 
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DCeleteFiles 

Deletes files using a simple wild card mechanism. The command first asks 
for the name of the directory to be searched and then asks for the partial 
file name for the search. The partial file name is the initial characters 
of the file names you want. For example, if you type 'ABC', the Filer 
searches for any file beginning with 'ABC'. If you type <cr>, all files in 
the directory match. After the directory search, D(eleteFiles prompts you 
to enter whether or not you want to delete the files, if any, that match 
the partial name. Type <ESC> to stop file deletion before going through 
the whole directory. 



THE PRIVILEGED FILER 

The P(rivFiler command line is: 

PrivFiler: 0(nline, E(ject, F(ix, Knit, Z(ap, N(ewTwig, W(riteBT, Q(uit, ? 

As with the Filer, the ? command flips to the other half of the PrivFiler's 
command line which is: 

D(ump 



0(nline 

Lists each currently mounted volume and the device it is mounted on. It 
also prints the name of the current working directory. 

E(ject 

Ejects a Twiggy disk from the specified device. Note that the button on a 
drive will not eject a disk; you must use the E(ject command. However, the 
command does not eject a disk that is not mounted. 

F(ix 

Invokes the Scavenger, the volume restoration utility program. It recovers 
lost space on a volume and repairs damaged file structures. You cannot run 
the Scavenger against the OS boot volume. If you attempt to scavenge the 
boot volume, the Scavenger returns error 1228. 



Knit 

Creates an OS file system volume. The volume initialized must not be 
mounted. After you specify the device name (without the '-'), the Filer 
asks for the set up information it needs. If the device is a diskette (not 
a Profile or the network), the media is automatically formatted. 
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Although I(nit destroys the current volume contents, the Pascal directory, 
if it is a small one, is untouched. Thus, the Monitor can still read the 
volume. Once you have initialized the volume, remember to mount it so you 
can use it. Boot tracks are automatically written to any initialized 
device as long as it is not the boot device . 

DO NOT attempt to Initialize an illegal device. 

Z(ap 

Invalidates an OS file system volume. To use the volume again, you have to 
initialize the volume the next time you start up the OS. If you change 
your mind after Zapping a volume, just Zap it again. Zap makes the volume 
appear to be an unmountable non-OS volume. The Z(ero command in the 
Monitor is not equivalent to Zap. 

N(ewTwig 

Formats a Twiggy diskette. The command prompts for the device name; 
"UPPER" or "LOWER" are appropriate names for Twiggies. After formatting 
the diskette, you should initialize it as an OS volume. Note that you are 
no longer have to format a diskette before you initialize it. 

W(riteBT 

Writes boot track information on an initialized Twiggy diskette or Profile 
to allow you to boot the standalone OS. NOTE: you can't write boot tracks 
on your boot volume. Instead, boot the OS from another Profile or Twiggy, 
attach your boot Profile to the N-port card, and then write boot tracks to 
it. Users following the standard OS installation procedures should not end 
up with a boot volume without boot tracks. Because boot tracks are 
automatically written when a volume is initialized, this function is of 
minor usefulness outside the OS group. 

D(ump 

Provides a nicely formatted hexadecimal and ASCII dump of any page in the 
Lisa file system. The OS group uses D(ump primarily as a debugging aid. 

Q(uit 
Quit exits the PrivFiler and returns you to the OS command shell. 
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THE ASYNCHRONOUS FILE SYSTEM 

Because your OS volume can only be on a Profile or a Twiggy, the OS blocks 
a process calling a system procedure that involves an I/O operation until 
the operation is complete. If there is a ready process at that time, the 
scheduler starts that process running during the time necessary for the I/O 
operation. 

This feature may improve overall performance of the OS. However, it can 
cause some problems. It is possible with this feature that writeln 
messages from several processes can get interspersed. This occurs if a 
writeln message from one process interrupts a writeln message from another 
process currently blocked for an I/O operation. 

Although this feature should not affect application programs, problems may 
occur with executing processes that share variables. A situation that 
could cause problems with shared data is the following. A process sets up 
a shared data address and then calls READJDATA to this address. The 
READ_DATA call blocks this process and allows a second process, possibly of 
lower priority, to run. If the second process attempts to use the shared 
data, it might receive erroneous data. If you have any problems protecting 
shared data, consult the OS group. 



OS PERFORMANCE 

This section explains the file system improvements that are part of the 5.2 
release of the Operating System and suggests how you can take advantage of 
them to improve program performance. Optimizations occurred in the 
f o 1 lowing a re as : 

• Creation and killing of objects 

• Allocation and deallocation of space 

• Multiple -block I/O 



Reorganizing the catalogs speeded up creating and killing objects. The OS 
now uses a hashing technique to map an object name to a location within a 
catalog. Other internal reorganizations further reduce the I/O time 
required for most catalog accesses. 

In order to accomplish these changes in the 5.2 release time frame, the 
structure of a catalog entry remains the same. However, a catalog now has 
a fixed size without linked entries. The larger fixed-size catalog causes 
the only known performance degradation: a significant slowdown of 
Get_Next_Entry for catalogs that are nearly empty. Hopefully, this problem 
will be solved by the next OS release. 
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Space allocation and deallocation no longer write page label (hint) 
information. The write operation is postponed until data is written to the 
file because I/O has to occur at that time anyway. The implications of 
this change are: 

• Although allocation and deallocation are significantly faster, 
reliability may be somewhat reduced. It is very important to 
use the recommended shutdown techniques discussed earlier to 
guarantee that the file system information is flushed to disk 
in a consistent state. 



• 



Because automatic allocation on writes is still implemented, 
explicit allocation is useful mainly for guaranteeing the 
availability of disk space rather than for performance benefits. 

Major optimizations were made to take advantage of any opportunity to do 
multiple -block I/O. The larger the request, the better the increase in 
speed is likely to be. Conversely, you will probably see no significant 
improvement in I/O operations that deal with only one byte at a time. 
However, there should be some improvement of speed in such I/O operations 
due to the fact that automatic write through to the disk no longer occurs, 

To summarize, create and kill are much faster, allocate and deallocate, 
although much faster, are now useful mainly for managing availability of 
disk space, and reading and writing multiple blocks of data at a time is 
much faster. It is hard to state how much faster these operations are; 
feedback from user tests would be much appreciated. However, please see 
the Operating System group if you don't notice significant improvement in 
the above areas . 



PRINTERS AND RS-232 INPUT/OUTPUT 

The Operating System supports the parallel ports and one serial RS-232 
port; the other RS-232 port is reserved for Lisabug on the standalone OS. 
The parallel ports on the 4-port card are named -slotxchany-any thing, where 
x and y are numbers 1 through three depending on the configuration. The 
device pathname for the OS supported RS-232 port is '-RS232B-anything' 
where 'anything' is any sequence of characters. RS232B is the leftmost 
port when facing the front of the machine. There is no device control 
required for printing on the parallel ports. The remainder of this section 
is devoted to serial printing. 

Follow the directions in this paragraph to set up a printer. Set the 
printer to handle 1200 baud serial communications. Connect the printer 
cable to a modem eliminator, and connect the modem eliminator to the RS232B 
port. If you want to connect the printer to a Soroc instead, set the Soroc 
to 1200 baud (set its rotary switch to 6) and connect the Soroc to the 
RS232B port using a standard Lisa-to-Soroc cable. 
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The default configuration is no parity, DTR handshake, 1200 Baud. You can 
change the configuration by using the DEVICE_C0NTR0L procedure. A sample 
program fragment that calls DEVICE_C0NTR0L follows. 

VAR 

cparm: dctype; 
errnum: integer; 
path: pathname; 

BEGIN 

path:='-RS232B'; 

cparm.dcversion:=2; (* note version change *) 

cparm.dccode:= « w »; (* see below *) 

cparm.dcdata[0] : = « x »; 

cparm.dcdata[l] := « y »; 

cparm. dcdata[2] := « z >>; 

DEVICE_C0NTR0L (errnum, path, cparm) ; 

END; 



« w », « x », « y >>, and << z » are defined as follows: 



FUNCTION 



« w » 



« x » 



« y » 



« z » 



Group A — Parity: 

No parity 

Odd parity, no 
input parity 
checking 

Odd parity 

Even parity, no 
input parity 
checking 



Even parity 1 

Group B — Output Handshake: 
DTR handshake 2 
X0N/X0FF handshake 3 
delay after Cr, LF 4 
Group C — Baud rate: 5 



ms delay 
baud 
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FUNCTION « w » « x » « y » « z » 

Group D — Input waiting: 

wait for full line 6 

return whatever rec'd 6 1 — — 

Group E — Input handshake: 

no handshake 7 — — 

9 -1 -1 65 

DTR handshake 7 

X0N/X0FF handshake 8 

Group F — Input type-ahead buffer: 

flush only 9 

flush & re-size 9 

flush, re-size, 9 
and set thresh 

Group G — Disconnect Detection: 

none 10 

device on 

RS232B 10 -128 



To change the configuration, call DEVICE_C0NTR0L for the option you want in 
each group. You can set baud to any standard rate. However, 3600, 7200, 
and 19200 baud are available only on the RS232B port. 

'Low' and 'Hi' under Group F set the low and high threshhold in the type 
ahead input buffer. When 'hi' or more bytes are in the input buffer, X0FF 
is sent or DTR is dropped. Then when 'Low' or fewer bytes are in the type 
ahead buffer, XON is sent or DTR is re-asserted. The size of the type 
ahead buffer can be anywhere between and 64 bytes inclusive. 

Once the device is properly configured, OPEN a pathname 'RS232B-anything' 
where 'anything' can be any string of characters. You can now WRITE__DATA 
and READ DATA with any size data block to the refnum opened. 



-1 


-2 


-2 


bytes 


-2 


-2 


bytes 


low 


hi 
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STACK SIZE 

The stack size that a process requires depends on several factors. These 
include the amount of storage necessary for program global variables, 
regular unit global variables and intrinsic unit global variables,- but do 
not include shared intrinsic variables. 

Besides the static stack space requirements, a process also requires stack 
space dynamically for procedure stack frames. These stack frames contain 
the procedure linkage information, procedure local variables, and space for 
temporary expressions. The initial amount of dynamic stack space is 
obtained from the program file the process is to execute and is allocated 
when the OS creates a process. The default initial dynamic stack size is 
10K (set by the Linker). The user can set the initial dynamic stack size 
to any desired value using the +S option of the Linker. 

During the course of execution, it is possible for a program to require 
more dynamic stack space than is currently allocated to the stack (stack 
overflow). When this occurs, the operating system automatically expands 
the stack by the necessary amount. Stack expansions occur as needed until 
an expansion would make the stack larger than the maximum stack size 
contained in the program file. The default value for maximum stack size is 
128K (again set by the Linker). You can set the maximum stack size to any 
desired value using the +T option of the Linker. 

Under the current system, if a process requires a stack expansion that 
would cause the stack to exceed the maximum stack size, the process gets a 
bus error and enters LisaBug. Once in LisaBug, the system displays the bus 
error message and allows the user to do any debugging desired. To 
continue, type 'g' to exit LisaBug and allow the OS to abort the process. 

Under the final (production) system, the Operating System terminates a 
process needing more stack space than the maximum. The cause of the 
termination, located in the exception information block associated with the 
SYSJTEKMINATE exception, will indicate 'stkjoverf low' (see Unit Syscall). 

Currently, the Operating System does not allow a stack size greater than 
128K (the size of a hardware segment). So if you specify a value greater 
than 128K in either the +S or +T option, the OS lowers it to 128K when the 
process is created. Note also that there can be a performance penalty 
associated with stack expansion since Memory Manager must be run in order 
to make space (possibly causing I/O) for the larger stack segment. 
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INTRINSIC UNITS 

To use Intrinsic Units under the OS you need the Monitor release 8.0 
versions of the compiler and code generator, the 8.2 versions of the 
Intrinsic Unit Manager and Intrinsic Unit Linker, an INTRINSIC. LIB file, 
and the linked library file IOSPASLIB.OBJ found on the OS release disks. 

The INTRINSIC. LIB file used must contain the 4 units that comprise Pas Lib. 
These are units 1 (PASLIB), 102 (BLKIOINT), 103 (BLOCKIO), and 104 
(PASHEAP). The INTRINSIC. LIB file may contain anything else that you 
require for the application. Before using the INTRINSIC. LIB and 
IOSPASLIB.OBJ to link a new unit or program, you must I(nstall the 
IOSPASLIB.OBJ from the OS release disk with the Intrinsic Unit Manager. 

The INTRINSIC. LIB file, IOSPASLIB.OBJ file, and any other library files 
required must be on the Monitor root volume and the OS volume before 
executing programs under the OS. 

You must compile programs that call OS routines using the SYSCALL unit. If 
a program calls anything from the privileged OS interface, you must include 
the PSYSCALL unit as well. In addition, you must link programs calling OS 
routines from either interface with IOSPASLIB.OBJ. 

Because both the INTRINSIC. LIB file and the various library files are 
required to run any programs that use Intrinsic Units, several problems can 
occur if you are not careful about keeping these files consistent with each 
other. If a library file is ever changed, you must re-install it in 
INTRINSIC. LIB, and you must transfer both the new library file and the new 
INTRINSIC. LIB to the OS volume. 

When you transfer a new INTRINSIC. LIB file to the OS volume, you must also 
change the memory resident copy of INTRINSIC. LIB. You can change the 
memory resident copy of the file either while in the T(ransfer command of 
the F(iler or later with the L(ib command of the Shell (see the 
descriptions of these commands for details). 

If any of these steps are omitted, various errors can occur. For example, 
if you define a new Intrinsic Unit, build a program that uses the unit, but 
forget to transfer and change the INTRINSIC. LIB file on the OS volume, 
Make__Proces s returns an error saying that the unit was not found in the 
Intrinsic Unit Directory. The error occurs because it is not in the memory 
copy of INTRINSIC. LIB. 

As an aid in tracking these kinds of errors, the OS Loader currently 
displays the Intrinsic Unit number and name that was not found on the 
screen. This display will not be in the production system. Similar errors 
occur when you change the name or type of a unit and forget to transfer 
over the new INTRINSIC. LIB and/or library file before executing a program 
that uses the unit. 
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More complicated errors can occur if the size of a shared code segment 
associated with an Intrinsic Unit or its location in a library file changes 
and the new INTRINSIC. LIB and/or library file is not transferred to the OS 
volume. In this case, the error is not detected until the code segment is 
swapped into memory. At this point, you get the message 

*** Error swapping in private code segment # nn for process id # pp 

OR 
*** Error swapping in shared code sement # nn (segname) for process 
id # pp 

where nn is the code segment number the application process uses, segname 
is the name of the shared segment from Intrinsic. Lib, and pp is the process 
identification number of the process for whom the segment is swapped in. 

If the swap-in error is for a shared segment, it is generally due to an 
inconsistency between Intrinsic. Lib and the library file containing the 
shared segment. If this is the case, the correct Intrinsic. Lib and the 
library file associated with the bad segment are probably not on the OS 
volume. 

If the swap-in error is for a private segment, it is generally due to 
either an improper link or a bad spot on the disk. To solve this problem, 
relink the program and transfer the relinked version to the OS volume. 

Regardless of the kind of swap-in error, type < ret > to continue. The OS 
terminates the failing process and the information block associated with 
the process's SYSJTERMINATE exception indicates that the OS is terminating 
the process due to a swap-in error. 



PASLIB 

The standalone OS does not support some of the Pas lib routines. The 
remainder of this section explains how you use PASLIB routines in the OS 
world. If an unsupported function is called in the standalone OS, the 
system displays the following message: 

MONITOR TRAP (E) occurred, index-<iiii> (routine name) in process of gid <gggg> 

where <iiii> is the routine's index to the Monitor's TRAP E handler. See 
the Pascal Development System Internal Documentation for the identity of an 
index without a routine name. 

The standalone OS does not support unit 10 routines such as Uni tread and 
Unitwrite and does not support the seek routine. However, it does support 
the GOTOXY routine. 
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The Pas lib routines for value range check and string index check run in the 
OS environment. If the range check indicates an error in OS code, a system 
error is signalled. The message displayed is: 

VALUE RANGE ERROR in system code! 

value to check = <vwv> lower bound = <nnnn> upper bound = <uuuu> 

return pc = <pppppp> caller a6 = <cccccc> 

Going to Lisabug, type g to continue. 



where: 



<pppppp> is the address of the next statement of the call 
to the range check routine in Pas lib, 

<cccccc> is the address of the link field at the time of 
the call to pas lib 



or: 



ILLEGAL STRING INDEX in system code! 

value to check = <vvw> lower bound = <nnnn> upper bound = <uuuu> 

return pc = <pppppp> caller a6 = <cccccc> 

Going to Lisabug, type g to continue. 

In this case and for other errors in system code, use the OSQUIT facility 
described earlier instead of typing g to continue. If you type g and try 
to continue, you get system error 10201 and you must reboot the system. 

If a range check error occurs in application code, the system exception 
'SYS__VALUE_00B' is signalled. The message displayed is: 

VALUE RANGE ERROR in process gid <gggg> 

value to check = <vvvv> lower bound = <nnnn> upper bound = <uuuu> 

return pc = <pppppp> caller a6 = <cccccc> 

Going to Lisabug, type g to continue. 



or: 



ILLEGAL STRING INDEX in process of gid <gggg> 

value to check = <ww> lower bound = <nnnn> upper bound = <uuuu> 

return pc = <pppppp> caller a6 = <cccccc> 

Going to Lisabug, type g to continue. 



If the process has not declared an exception handler for the exception that 
occurs, the system exception handler is entered after you type 'g' to 
contine. It terminates the process. If the process has declared a 
handler, the handler is called after you type 'g', and the process then 
continues execution. 

The intrinsic procedure HALT calls TERMINATEJPROCESS without passing an 
event . 
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The block 10 routines, RESET, REWRITE, BLOCKREAD, BLOCKWRITE, and IORESULT, 
act in the operating system just as they do in the Monitor. In fact, RESET 
and REWRITE accept both Monitor and OS file names. 

In order to distinguish between the two types of files in RESET and 
REWRITE, Paslib has adopted the following file naming convention: a file 
name designates a Monitor file only if the name includes a colon (:) AND 
does not begin with a dash (-). All other files are considered OS files. 



You can override the file system mode with a call to SetMPrefix. This call 
allows you to choose the file system you want; its format is: 

procedure SetMPrefix (var errnum: integer; 

prefix: vid); 



where vid is of type string [ 7 ]. If you set prefix to '%%0S', later 
calls to RESET or REWRITE assume that file names refer to OS files. If you 
set prefix to '%%M0', subsequent calls to the two routines assume that file 
names refer to Monitor files. The file naming conventions given above are 
in effect if you set prefix to '%%B0'. The file system mode you choose 
remains in effect until the next call to SetMPrefix. 

Before calling SetMPrefix, you must declare it as external. This call will 
no longer be necessary once the entire development system is running on top 
of the OS and OS support of Monitor volumes isn't necessary. 

The OS file system mode does not support the file name construct [X], where 
X is a number of blocks. There is no need for the OS to support this 
syntax because an OS file expands as needed, and will not take the largest 
available space if X is not specified. In fact, if you do append the 
construct to the file name, it becomes part of the file name. 

IORESULT, in the OS file system mode, returns the same error values as 
Monitor files, but the error return numbers are in the OS file system 
range. The current mapping of OS to UCSD file system error values is: 

OS Error Value UCSD Error Value 



882 8 

894 6 

921, 946 7 

941 5 

948 10 

Other errors are not mapped. The above error mappings will no longer exist 

once the OS stops supporting Monitor files. 
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Note also that IORESULT now returns error 11 (duplicate file) as a warning 
(-11) and completes the operation as normal when the error results from a 
second REWRITE of a file without a CLOSE after the first REWRITE. This 
change allows the user to decide whether to continue the program if the 
error occurs because of a program crash or to stop execution if there is a 
name conflict with another program that has already done a REWRITE to the 
same file. 

For Monitor files, only units 5, and 9 through 20 are considered block 
structured devices. Block 10 to a non-block structured device is not 
supported. IORESULT can return an additional error number: 

17 - device error, non-zero value returned from last LISAIO call 

Text file block 10 works as expected. RESET and REWRITE of a text file 
(.TEXT suffix) sets the current block number to 2, thereby bypassing the 
text file header blocks. Note that RESET and REWRITE only accept names of 
files on the working device. In addition, the two routines do not support 
the new Monitor file name syntax (DEV/VOL: FILE) yet. 



THE PASCAL HEAP 

The heap is one contiguous piece of memory. It obtains a contiguous piece 
of memory with a call to Make_Dataseg. The heap works automatically 
without any initialization call; there are default values for size of the 
heap, the LDSN used, etc. 

Most users of the heap should use it the same way as they use the Monitor 
heap. For those having special needs, there is a call, PLINITHEAP, that 
specifies the LDSN, the initial heap SIZE, whether the heap can be swapped 
to disk, and the heap DELTA size. When you use PLINITHEAP, you must call 
it before making a call to the other heap routines. 

PLINITHEAP ( ERROR, REFNUM, SIZE, DELTA, 9, FALSE); 



PLINITHEAP is defined as follows in the PASLIBCALL unit: 

procedure PLINITHEAP (var ERNUM, REFNUM: integer; 

SIZE, DELTA: longint; 
LDSN: integer; 
SWAP ABLE: boolean); 



where ERNUM is the error number returned if the procedure has any problems 
making a data segment having a mem size of SIZE bytes, LDSN is the LDSN 
used for the heap ( the default is 5), REFNUM is the refnum of the heap, 
DELTA is the amount the data segment increases when the current space is 
used up (If you use a large heap, use a large number for DELTA), and 
SWAP ABLE is the boolean that determines whether the system can swap the 
heap data segment out to disk if it needs to. 



Calvert 25 July 23, 1982 



Confidential Guide to OS 



When a Pascal program starts execution, there is no heap space allocated 
(no data segment made). On the first call to one of the heap routines or 
on the first PUNITHEAP call, the heap is created with either a default 
size of 16k bytes or the size specified in the PLINITHEAP call. 

PLINITHEAP makes the heap as a private data segment so that the OS will 
remove it when the process calling PLINITHEAP terminates. Note that when 
the heap is initialized, size and delta are put on 512 byte block 
boundries. Therefore, if you use the PLINITHEAP call and specify values 
for size and delta that don't fall on block boundaries, the procedure 
increases the values to the next block boundary. 

If the heap runs out of space while it is being used, the size of the heap 
is increased by the default of 16k or the DELTA specified in PLINITHEAP. 
The default LDSN used is LDSN 5. If you want a different LDSN for the heap 
data segment, call PLINITHEAP. Remember that the size of a data segment is 
limited by the LDSN you use. For LDSN 16, you can only get 128k (actually 
96k safely), for LDSN 15 256k, for LDSN 14 384k, .... 

If SWAPABLE is true, the heap is made with disc__size equal to SIZE so the 
data segment will not be memory resident. The default for SWAPABLE is 
false. When SWAPABLE is false the procedure creates a data segment that 
has a disc size of which makes it memory resident. 

The unit PASLIBCALL contains the interface for the PLINITHEAP call. 
PASLIBCALL will contain the interface to all procedures that effect the 
PASLIB. PASLIBCALL will be released with Tippe. 

Currently, the OS supports the built in Pascal heap routines NEW, MEMAVAIL, 
MARK, and RELEASE. 

If you call NEW and there is not enough space, the size of the heap is 
increased by the default of 16k or the deltasize specified in PLINITHEAP. 

MEMAVAIL gives you the maximum number of words you could ever expect to get 
and takes into account the LDSN you used as well as the amount of free 
space the OS currently has available. If there is another process using 
memory concurrently, it's use of memory also effects MEMAVAIL. MEMAVAIL 
does not show the amount of memory left in the heap's data segment alone 
since the heap's data segment can grow and shrink over time. 

MARK works as it does in the Monitor. 

If you release the heap to a point within the original size of the heap 
data segment, the heap data segment is reduced to its original size. Other 
than this, RELEASE works as it does in the Monitor. 

The current heap could be replaced later by heap routines within the 
standard storage manager. There are currently implementation dependencies 
in the Compiler, and probably other parts of the system, that require a 
UCSD style contiguous heap. If these dependencies are removed in time, we 
may go to a fancier heap for first release that contains DISPOSE and 
possibly other features. 
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THE OS INTERFACE 

UNIT syscall; 
INTRINSIC; 

INTERFACE 



(* system call definitions unit *) 



CONST 

max__ename = 32; 
len_exname = 16; 
size exdata =11; 



size__etext = 9; 
size waitlist - 10; 



call_term = 0; 
ended = 1 ; 
selfjcilled = 2: 
killed - 3 
fthr_term = 4 
bad__syscall = 5 
bad__errnum = 6 
swap__error = 7 
stkjoverf low = 8; 
data_overf low = 9; 
parity err = 10; 



def__div zero 


= 


11 


def __value_o ob 


= 


12 


def_ovfw 


= 


13 


def_nmi__key 


= 


14 


def__range 


= 


15 


def str index 


= 


16 



bus_er ror =21; 
addr__error = 22; 
illg_inst =23; 
priv__violation = 24; 
line_1010 = 26; 
line 1111 = 27; 



div__zero 

value_oob 

ovfw 

nmi__key 

value__range 

str index 



31 
32 
33 
34 
35 
36 



(* maximum length of a file system object name *) 

(* length of exception name *) 

(* 48 bytes, exception data block should have the same 

size as r__eventblk, received event block *) 

(* event text size - 40 bytes *) 

(* size of wait list - should be same as reqptr list *) 



(* exception kind definitions for 'SYSJTERMINATE' 
exception *) 

* process called terminate_process *) 

* process executed 'end' statement *) 

* process called kill__process on self *) 

* process was killed by another process *) 

* process's father is terminating *) 

* process made invalid sys call - subcode bad *) 

* process passed bad address for errnum parm *) 

* process aborted due to code swap-in error *) 

* process exceeded max size (+T nnn) of stack *) 

* process tried to exceed max data space size *) 

* process got a parity error while executing *) 



default handler for div zero exception was called *) 

11 for value oob exception *) 

" for overflow exception *) 

" for NMI key exception *) 

11 for ' SYS_VALUE__00B ' excep due to value range err *) 

" for 'SYS VALUE OOB' excep due to string index err*) 



* bus error occurred *) 

* address error occurred *) 

* illegal instruction trap occurred *) 

* privilege violation trap occurred *) 

* line 1010 emulator occurred *) 

* line 1111 emulator occurred *) 

(* exception kind definitions for hardware exception *) 



(* excep kind for value range and string index error *) 
(* Note that these two cause 'SYS VALUE OOB' excep *) 
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TYPE 



pathname = string [255]; 

e_name = string [max_ename] ; 

names tring = string [20]; 

procinfoRec = record 

prog pathname 
global_id 
f ather_id 
priority 
state 
data_in 
end; 



pathname; 

longint; 

longint; 

1..255; 

(pactive, psuspended, pwaiting); 

boolean 



Tdstype = (ds shared, ds private); (* types of data segments *) 



dsinfoRec = 



record 

memjsize : longint; 
disc_size: longint; 
numb_open : integer; 
ldsn : integer; 
boundF : boolean; 
presentF : boolean; 



creatorF 
rwaccess 
segptr : 
volname: 
end; 



: boolean; 
: boolean; 
longint; 
e name; 



t_ex_name = string [len_exname] ; 

longadr = "longint; 

t_ex__state = (enabled, queued, ignored); 

p__ex_data = "t_ex__data; 

t__exjdata = array [0. .size_exdata] of longint; 

t__ex_sts = record 

ex_occurred_f : boolean; 

ex_state : t_ex_state; 

numjexcep : integer; 

hdl__adr : longadr; 
end; 



(* exception name *) 

(* exception state *) 

(* exception data blk *) 

(* exception status *) 

(* exception occurred flag*) 

(* exception state *) 

(* number of exceptions q'ed*) 

(* handler address *) 
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p_env_blk 
env blk = 


= ~env_blk; 
record 




pc ; 


longint 3 






sr . 


integer. 






dO • 


longint 3 






dl : 


longint 3 






d2 


longint 






d3 


longint 3 






d4 , 


longint j 






d5 


, longint 






d6 


' longint j 






d7 


: longint 






aO 


: longint 






al 


longint 






a2 


• longint 






a3 


: longint 






a4 


: longint 






a5 


: longint 






a6 


. longint 






a7 


: longint 






end; 




p term ex data = A term ex data; 
term ex data = record 






case excep_kind : 
call_term, 
ended , 

self killed, 
killed, 
fthr__term, 
bad syscall, 
bad errnum, 
swap__error, 
stk overflow, 
data_overf low, 
parity err : (); 

illg__inst, 
priv_violation, 

line 1010, 
lineal 111, 
def_div zero, 
def_value__oob, 
def__ovfw, 






def nm: 


L key 



Guide to the OS 



(* environment block to pass to handler *) 
(* program counter *) 
(* status register *) 
(* data registers - 7 *) 



(* address registers - 7 *) 



(* terminate exception data block *) 



longint of 



: (sr : integer; 
pc : longint); 
def range, 



(* due to process termination *) 



(* due to illegal instruction, 

privilege violation *) 

(* due to line 1010, 1111 emulator *) 



(* terminate due to default handler for 
hardware exception *) 

(* at the time of occurrence *) 



Calvert 



29 



July 23, 1982 



Confidential 



Guide to the OS 



def str index 



: (value__check 
upperjbound 
lower_bound 
return_pc 
caller__a6 
bus_error, 
addr_error 

: (fun field : 



terminate due to default handler for 
'SYS_VALUE_OOB' excep for value 
range or string index error *) 



integer; 
integer; 
integer; 
longint ; 
longint); 



bus 



(* due to 
packed record 

filler : 0..$7ff; 
r w flag : boolean; 



error or address error *) 
(* one integer *) 
(* 11 bits *) 



access adr 



i__n__f lag 
fun__code 

end; 

: longint; 



boolean; 
0..7; 



(* 3 bits *) 



end; 



inst_register : integer; 
sr__error : integer; 
pc error : longint); 



p_hard__ex_data = *hard_ex_data; 

hard_ex_data = record (* hardware exception data block *) 

case excep_kind : longint of 
div_zero, value_oob, ovfw 
: (sr : integer; 
pc : longint ) ; 
value_range , s tr_JLndex 
: (value check : integer; 



upper_bound 
lower_bound 
returnj>c 
caller a6 



end; 



integer; 
integer; 
longint ; 
longint); 



accesses = (dread, dwrite, append, private, global_refnum); 

mset = set of accesses; 

iomode = (absolute, relative, sequential); 

UID = record (*unique id*) 

a,b: longint 
end; 



times tmp_interval = record 

sec : longint; 
msec : 0..999; 
end; 



(* time interval *) 
(* number of seconds *) 
(* number of milliseconds within a second *) 
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info__type = (device_t, volume__t, object__t); 

devtype = (diskdev, pascalbd, seqdev, bitbkt, non__io); 

filetype = (undefined, MDDFfile, rootcat, freelist, badblocks, 
sysdata, spool, exec, usercat, pipe, bootfile, 
swapdata, swapcode, ramap, userfile, killedobject); 

entrytype= (emptyentry, catentry, linkentry, fileentry, pipeentry, ecentry, 
killedentry); 

fs__info = record 

name : e_name ; 
devnum : integer; 
machine_id : longint; 
case otype : info__type of 
device__t , volume_t : ( 

io channel : integer; 

devt : devtype; 

slot__no : integer; 

fs_size : longint; 

vol_size : longint; 

blocks tructured, mounted : boolean; 

opencount : longint; 

privatedev, remote, lockeddev : boolean; 

mount__pending , unmount_jpending : boolean; 

volname, password : e_name; 

fsversion, volnum : integer; 

volid : UID; 

blocksize, datasize, clustersize, filecount : integer; 

freecount : longint; 

DTVC, DTCC, DTVB, DTVS : longint; 

master_copy_id, copy_thread : longint; 

overmount_stamp : UID; 

privileged, write__protected : boolean; 

master, copy, scavenge__f lag : boolean; 

vol__lef t_mounted : boolean ); 

object__t : ( 

size : longint; 

psize : longint; (* physical file size in bytes *) 
lpsize : integer; (* logical page size in bytes for this file *) 
ftype : filetype; 
etype : entry type; 
DTC, DTA, DTM, DTB, DTS : longint; 
refnum : integer; 
fmark : longint; 
acmode : mset; 

nreaders, nwriters, nusers : integer; 
fuid : UID; 

eof , safety__on, kswitch : boolean; 
private, locked, protected, master__file : boolean; 
f ile__scavenged, file_closed_by_OS, f ile__lef t_open : boolean ) 
end; 
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dctype = record 

dcversion : integer; 
decode : integer; 

dedata : array [0..9] of longint; (* user/driver defined data *) 
end; 



t_waitlist = record 

length 
refnum 
end; 



(* wait list *) 
integer; 
array [0..size waitlist] of integer; 



t__eheader = record 

send_j>id : longint; 
event_type : longint ; 
end; 



(* event header *) 

(* sender's process id *) 

(* type of event *) 



t__event_text = array [0. .size_etext] of longint; 
p__r_eventblk = A r_eventblk; 
r__eventblk = record 

eventjheader : tjeheader; 
event_text : t_event__text ; 
end; 

p_s_eventblk = *s__eventblk; 
s eventblk = t event text; 



time__rec = record 

year : integer; 
day : 1..366; 

hour : -23.. 23; 

minute : -59. .59; 

second : 0..59; 

msec : 0. .999; 
end; 

chn_kind = (wait_ec, call_ec); 
t__chn_sts = record 

chn_type : chn_Jcind ; 

num__events : integer; 

open__recv : integer; 

open_send : integer; 

e c__name : pa t hn ame ; 
end; 

hour__range = -23.. 23; 
minute__range = -59.. 59; 



(* Julian date *) 



(* channel status *) 

(* channel type *) 

(* number of events queued *) 

(* number of opens for receiving *) 

(* number of opens for sending *) 

(* event channel name *) 
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(* File System calls *) 

procedure MAKE_FILE (var ecode: integer; var path: pathname; label_size : integer) ; 
procedure MAKE_PIPE (var ecode: integer; var path: pathname; label_size: integer); 
procedure MAKE__CATALOG (var ecode: integer; var path: pathname; label_size: integer); 
procedure MAKE_LINK (var ecode: integer; var path, ref : pathname; label_size: integer) ; 
procedure KILL_OBJECT (var ecode: integer; var path: pathname); 

procedure OPEN (var ecode: integer; var path: pathname; var ref num: integer; manip:mset) 
procedure CLOSE__OBJECT (var ecode: integer; ref num: integer); 



procedure READ_DATA (var ecode 

ref num 

data_addr 

count 

var actual 

mode 

offset 



integer; 

integer; 

longint ; 

longint; 

longint; 

iomode ; 

longint); 



procedure WRITE_DATA (var ecode : integer; 

ref num : integer; 

data__addr : longint; 

count : longint; 

var actual : longint; 

mode : iomode ; 

offset : longint); 

procedure FLUSH (var ecode: integer; ref num: integer); 

procedure LOOKUP (var ecode : integer; 

var path : pathname; 
var attributes : fs_info); 

procedure INFO (var ecode: integer; ref num: integer; var ref info: fs__info) ; 

procedure ALLOCATE (var ecode : integer; 

ref num : integer; 

contiguous : boolean; 

count : longint; 

var actual : longint); 

procedure TRUNCATE (var ecode : integer; ref num : integer); 

procedure COMPACT (var ecode : integer; ref num : integer); 

procedure RENAME ENTRY ( var ecode: integer; var path: pathname; var newname : e name ) 
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procedure READJLABEL ( var ecode : integer; 

var path : pathname; 

data__addr : longint; 

count : longint; 

var actual : longint ) ; 

procedure WRITE_LABEL ( var ecode. : integer; 

var path : pathname; 

data_addr : longint; 

count : longint; 

var actual : longint ); 

procedure MOUNT ( var ecode: integer; var vname : e_name; var password : e__name ; 
var devname : e_name); 

procedure UNMOUNT ( var ecode: integer; var vname : e__name ); 

procedure SET_WORKING__DIR ( var ecode: integer; var path: pathname ); 

procedure GET_WORKING_JDIR ( var ecode: integer; var path: pathname ); 

procedure SETJ5AFETY ( var ecode: integer; var path: pathname; on_off: boolean ); 

procedure DEVICE_CONTROL ( var ecode: integer; var path: pathname; 

cparm : dctype ); 

procedure RE SET_CATALOG (var ecode : integer; var path : pathname); 

procedure GET__NEXT__ENTRY (var ecode : integer; var prefix, entry : e__name); 

procedure GETJDEV__NAME (var ecode : integer; var path : pathname; 

var devname : e_name); 

procedure SET__FILE__INFO ( var ecode : integer; 

refnum : integer; 
fsi : fs__info ); 

(* Process Management system calls *) 

function My__ID : longint; 

procedure Info_Process (var errnum : integer; proc_id : longint; 

var proc_info : procinfoRec); 

procedure Yield_CPU (var errnum : integer; to_any : boolean); 

procedure SetPriority__Process (var errnum : integer; proc_id : longint; 

newjpriority : integer); 

procedure Suspend_J?rocess (var errnum : integer; procjld : longint; 

susp family : boolean); 
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procedure Activate_Process (var errnum : integer; proc__id : longint; 

act_f amily : boolean) ; 

procedure Kill__Process (var errnum : integer; proc__id : longint); 

procedure Terminate_J?rocess (var errnum : integer; event_ptr : p_s_eventblk); 

procedure Make__Process (var errnum : integer; var proc__id : longint; 

var progfile : pathname; var entryname : names tring; 
e vnt_chn_r ef num : int eg e r ) ; 

(* Memory Management system calls *) 

procedure make_dataseg(var errnum: integer; var segname: pathname; 

mem_size, disc_size: longint; var refnum: integer; 
var segptr: longint; ldsn: integer; dstype: Tdstype); 

procedure killjdataseg (var errnum : integer; var segname : pathname); 

procedure openjdataseg (var errnum : integer; var segname : pathname; 

var refnum : integer; var segptr : longint; 
ldsn : integer); 

procedure close__dataseg (var errnum : integer; refnum : integer); 

procedure size_dataseg (var errnum : integer; refnum : integer; 

deltamemsize : longint; var newmemsize : longint; 
deltadiscsize: longint; var newdiscsize: longint); 

procedure inf o__dataseg (var errnum : integer; refnum : integer; 

var dsinfo : dsinfoRec); 

procedure setaccess__dataseg (var errnum : integer; refnum : integer; 

readonly : boolean); 

procedure unbind__dataseg (var errnum : integer; refnum : integer); 

procedure bind_dataseg(var errnum : integer; refnum : integer); 

procedure info__ldsn (var errnum : integer; ldsn: integer; var refnum: integer); 

procedure f lush_dataseg(var errnum: integer; refnum: integer); 

procedure MEM_INFO(var errnum: integer; 

var swapspace, dataspace, 

cur codesize, max codesize: longint); 
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(* Exception Management system calls *) 



procedure declare_excep__hdl (var errnum : integer; 

var excep__name : t_ex_name; 
entry_point : longadr); 

procedure disable_excep (var errnum : integer; 

var excep__name : t_ex_name; 
queue : boolean) ; 

procedure enable__excep (var errnum : integer; 

var excep_name : t_ex__name ) ; 

procedure signal__excep (var errnum : integer; 

var excep_name : t_ex_narae; 
excep_data : t__ex_data); 

procedure info_excep (var errnum : integer; 

var excep_name : t_ex__name; 
var excep__s tatus : t__ex_sts); 

procedure flush_excep (var errnum : integer; 

var excep name : t ex name); 



(* Event Channel management system calls *) 

procedure make_event__chn (var errnum : integer; 

var event_chn__name : pathname); 

procedure kill__event_chn (var errnum : integer; 

var event_chn__name : pathname); 

procedure open_event_chn (var errnum : integer; 

var event__chn_name : pathname; 
var refnum : integer; 
var excep_name : t__ex_name; 
receiver : boolean) ; 

procedure close__event_chn (var errnum : integer; 

refnum : integer) ; 

procedure inf o_event_chn (var errnum : integer; 

refnum : integer; 
var chn_JLnfo : t_chn__sts); 

procedure wait_event_chn (var errnum : integer; 

var wait__list : t_waitlist; 
var refnum : integer; 
event ptr : p r eventblk); 



Calvert 36 July 23, 1982 



Confidential Guide to the OS 



procedure f lush_event_chn (var errnum : integer; 

refnum : integer); 

procedure send__event__chn (var errnum : integer; 

refnum : integer; 
event__ptr : p_s_eventblk; 
interval : times tmp__interval; 
clktime : time rec); 



(* Timer functions system calls *) 

procedure delay_time (var errnum : integer; 

interval : times tmp__interval; 
c lkt ime : t ime__r ec ) ; 

procedure get__time (var errnum : integer; 

var gmt__time : time_rec); 

procedure set_local__time__dif f (var errnum : integer; 

hour : hour__range; 
minute : minute_range); 

procedure convert_time (var errnum : integer; 

var gmt_time : time_rec; 
var local__time : time__rec; 
to gmt : boolean); 
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UNIT psyscall; (* privileged system call definitions unit *) 

INTRINSIC; 

INTERFACE 

(*$U object :syscall.obj *) 
USES syscall; 

const buff__too_small = 1158; 
ejsdubd - 1159; 
ddev_too_small = 1160; 
inv__shutdown__mode = 1161; 
pwr_already_off = 1162; 
badcmd__err = 1163; 
nottwig_err = 1164; 
notmounted_err = 1165; 
alreadymounted_err = 1166; 
notblockstr_err = 1167; 

maxILFile =64; { maximum intrinsic library file number } 



type 








vers info 


= record (* 


version information record *) 




PPrim V : 


integer 






PM V : 


integer 






GDV : 


integer 






MMPrimV : 


integer 






MMV : 


integer 






DSV : 


integer 






ExprmV : 


integer. 






ExmgrV : 


integer 






ECV : 


integer 






TimeV : 


integer 






VMV : 


integer 3 






SFV : 


integer 






PrimV : 


integer. 






UIV : 


integer 






InitV : 


integer. 






CUR V : 


integer 






OSVers : 


integer 




end; 
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ut_commands = (no__op, 
online, 
initvol, 
zap, 

dumpdata, 
setf strace, 
f sscavenge, 
writeBT, 
format, 
verify, 
eject, 

f lushbuffers , 
boot_unmount , 
boot__remount , 
copy_yolume, 
shut__down_sys , 
mount_BD); 

sm_type = (res tart_s hell, reset_machine, kill__power); 

ScvOptions = ( no__abort, no_kill, no__pipes, no_discard ); 

ut_parmt = record 

gp__parm : longint; 

case command : ut_commands of 

no__op , 

online, 

f lushbuffers, 

boot__remount : ( ); 

shut__down__sys : (sd_mode : sm__type ); 

initvol : (idev__name : e__name; 
pages : longint; 
newvolname : e__name; 
newpas sword : e__name ); 

zap, 

writeBT, 

format, 

verify, 

eject : (dev__name : e__name ); 

dumpdata : (ddevjiame : e__name; 

pagenum : longint ); 

setf strace, 

boot_unmount : (level : integer ); 
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fs scavenge : (sdev_name : e__name; 

soptions : ScvOptions ); 



copy_volume : (from_dev : e_name; 

to_dev : e_name; 

buffaddr : longint; 

buff size : longint ); 

mount__BD : (mon_unitnum : integer; 

twigjunitnum : integer ) (* 1 = UPPER *) 

(* 2 = LOWER *) 
end; 

ioop = (readop, writeop); 

refnum__type = (frefnum, dsrefnum, ecrefnum); 

openrec = record (* open list info record *) 

procid : longint; 
refnum : integer; 
refntype : refnum__type; 
globalrefn : boolean; 
end; 

Tlog_cmds = ( log_dump , log_f lush,log__reset , log_s hut down ) ; (*logging commands*) 



{ Intrinsic Library File # list } 

IFileRange = 1 . .maxILFile ; 

lf_list = packed array [IFileRange] of boolean; { list of library files used 

by a program } 



{ Lisa Office System parameter memory type } 

pmByteUniqueForAllTheDamnCryBabies = -128.. 127; 

pMemRec = array [1.. 62] of pmByteUniqueForAHTheDamnCryBabies; 



{configuration stuff: } 

tports = (seriala, serialb, parallel, slotll, slotl2, slotlX, 
slot21, slot22, slot2X, slot31, slot32, slot3X); 

boot__tports = (uppertwig, lowertwig, pport, b_slotll, b__slotl2, b_slotlX, 
b slot21, b slot22, b slot2X, b slot31, b slot32, b slot3X); 
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card_types = (no_card, apple_card, n_jport__card, net_card, laser_card); 
slot_array = array [1..3] of card__types; 



procedure POPEN (var ecode : integer; 

var path : pathname; 

var refnum : integer; 

manip : mset; 

var allowed : boolean ); 

procedure protect (var ecode : integer; 

var path : pathname; 

ismaster : boolean; 

m__serial_no : longint ); 

procedure get__serial_no (var ecode : integer; var s_no : longint); 

procedure GET_OPEN__LIST (var ecode : integer; var devname : e__name; 

var openinfo : openrec); 

procedure fsjutilities (var ecode : integer; var paras : ut_parmt); (* replaces OSVM 

procedure lis t_vers ions (var info : vers_info); 

procedure lockseg (var errnum: integer); 

procedure unlocksegs (var errnum: integer); 

procedure unitio (var errnum : integer; devnum : integer; bufadr : longint; 
numblocks : longint; blocknum : longint; op : ioop); 

(* a subsitute routine for uni tread and unitwrite *) 

procedure monio (var ch : char; op : ioop); 

procedure set__time (var ecode : integer; time : time__rec); 

procedure Change__Directory (var errnum : integer; restartShell : boolean); 

function LOGGING: boolean; 

procedure LOG(var errnum: integer; ptr_arr: longint); 

procedure LOG_NEWCMD(var errnum: integer; cmd: Tlog__cmds); 

procedure Size__Stack(var errnum: integer; delta__size: longint); 

procedure List__LibFiles (var errnum : integer; var progfile : pathname; 

var file list : If list); 
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procedure LibFileName (var errnum : integer; lf__num : integer; 

var lf__name : pathname); 

procedure Set_DebugMode (var errnum : integer; on_off : boolean); 

procedure Read_PMem (var errnum : integer; var my__pMem : pMemRec ); 

procedure Write_JPMem (var errnum : integer; my_pMem : pMemRec); 

procedure pset_f ile__inf o ( var ecode : integer; 

refnum : integer; 
fsi : fs_info ); 

procedure pset_vol__inf o ( var ecode : integer; 

path : pathname; 
fsi : fs__info ); 

function OSBOOTVOL(var error : integer) : boot_tports; 

procedure GET_CONFIG__NAME( var error : integer; 

devpostn : tports; 
var devname : e__name); 

function DISK__LIKELY(var error : integer; 

devpostn : boot__tports) : boolean; 

procedure CARDS_EQUIPPED(var error : integer; 

var in slot : slot array); 
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ADDITIONS TO THE OS 

This section documents all the changes to the OS that have occurred since 
the last release of the OS Reference Manual. When the manual is updated, 
the material will be deleted from this section. 



NEW OS PROCEDURES 

A new data segment call named Info_Address was added in release 5.2. This 
call returns the refnum of the data segment that maps to the address that 
the user specifies in the call. The definition of the call is: 

Info_Address (var errnum: integer; 
address: longint; 
var refnum: integer); 

where errnum is the return status of the call, address is the address that 
is converted to a data segment number, and refnum is the refnum of the data 
segment that maps to the address 'address'. 

Info_Address can return any of the following errors: 

303 - No data segment bound to the address 

314 - Address does not fall within the valid ldsn range 

1998 - Invalid parameter address 

MEM__INF0, defined below retrieves information about the memory resources 
that the calling process uses. 

MEM__INF0 (var errnum : integer 
var swapspace; 
da t as pace; 
cur__codesize; 
max_codesize: longint) 

where: 

swapspace = amount of system memory available (in bytes) 
for swapping 

dataspace = amount of memory (in bytes) the calling process 
requires for its bound data areas. This value 
includes the stack of the process and the data 
segment for shared intrinsic data. 

cur_codesize - size (in bytes) of the calling segment. 

max_codesize = size (in bytes) of the longest code segment within 
the address space of the calling process. 
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The Set_File_J[nf o system call, added in release 5.2, alters certain status 
information associated with a file system object. The call format is: 



Set__File_Info (var ecode: integer; 

refnum: integer; 
fsi: fs info); 



where ecode is the error return code, refnum is the refnum of the object, 

and fsi is the fs information record that the OS calls LOOKUP and INFO 

use. Note that the object that refnum identifies must be open at the time 
of the call to Set_File__Inf o. 

Set___File__Inf o alters the status information of the named object to conform 
to the values of the information record named in the call. Call INFO and 
set the values in fsi you want to change before calling this procedure. 

Currently, Set_File__Info can change the following status fields: 

• file_scavenged 

• file__closed_by__OS 

• file_lef t_open 

DATA SEGMENT CHANGES 

From OS release 5.1 on, OPEN_DATASEG is much less sensitive to the values 
of LEOF and PEOF within the data segment being opened. The results of an 
OPEN__DATASEG call under various conditions are outlined below: 

Condition Resulting Data Segment 



< LEOF <= 128kb memory size = LEOF; disk size = PEOF 

PEOF = any value errnum = 

LEOF > 128kb errnum = 306 (data segment too big) 
PEOF « any value 

LEOF = memory size - PEOF; disk size = PEOF 

< PEOF <= 128kb errnum = -320 (a warning) 

LEOF = memory size = 128kb; disk size = PEOF 

PEOF > 128kb errnum = -320 (a warning) 

LEOF = memory size =512 ; disk size = 

PEOF = errnum = -320 (a warning) 

Those conditons which result in a warning error (-320) should be checked 

via INFO__DATASEG to verify that the resulting data segment has the desired 

memory and disk sizes before the segment is used. 
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In release 5.2 of the Operating System the calling sequence for 
Make_Dataseg has changed to: 

Tdstype = (ds_shared, ds_private) 

Make_Dataseg (var errnum: integer; 

var segname: pathname; 

mem_size, discjsize: longint; 
var refnum: integer; 
var segptr: integer; 

ldsn : integer; 

dstype : Tdstype); 



All parameters are the same as before except dstype. dstype now specifies 
whether the data segment created is shared or private. The segment is 
located on the disk that segname specifies. Note that a null segname is no 
longer valid. 

Info_Dataseg returns the attributes of a data segment in the record 
Dslnfo. Release 5.2 adds two values to this record: segptr and volname. 
segptr is of type longint and represents the base address of the data 
segment; volname is of type e__name and represents the volume that contains 
the data segment. 



CHANGES TO LISABUG 

This section presents the additions and fixes to Lisabug that were made in 
the 5.2 release of the OS. These changes involve stack crawl and 
breakpoints. 

The stack crawl command, SC, is now very robust. It correctly lists all 
stack frames even in domain 0. 

This version of Lisabug allows you to run a program with the initial 
breakpoint set at the first instruction of the program. See the 
description of the D(ebug command in the section on the OS Shell in this 
manual for the details of this feature. 

You can now set a breakpoint in code that is not in memory. As the code is 
swapped in and out, the OS automatically restores the breakpoints 
associated with the code currently in memory. Note that although you can 
set breakpoints in code that is not in memory, you can only use symbols for 
the code, such as procedure names, when the code is in memory. Therefore, 
you must use the logical address form of the breakpoint command when 
setting a breakpoint in code not in memory. However, once the code is 
swapped in, you can use the symbolic form of the breakpoint • 
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Another added breakpoint command feature is a format for specifying 
breakpoints on a process basis. The syntax of the new format is: 



>br procid : address 



When the process specified by procid reaches 'address', the breakpoint is 
taken. However, if any other process reaches 'address', the breakpoint is 
not taken. If you don't specify a procid in a breakpoint command, the OS 
assumes the procid of the currently executing process (most application's 
programmers will probably use this mode). Note that to reflect the change 
of associating a breakpoint with a process, Lisabug now displays the procid 
of the currently running process as well as the domain currrently in 
effect. 

Although only the OS group will probably do this, if you wish to set a 
breakpoint in the Operating System, specify as the procid in the 
command. Using as the procid, causes all processes to take the 
breakpoint in the OS when they reach the specified address. 



ERROR CHANGES AND ADDITIONS 

Release 5.2 contains a new error for OpenJDataseg, Make__Dataseg, and 
SizeJDataseg. This error, 315, indicates that the operation could not be 
completed because it might cause a data lockout situation. 

Open_Dataseg can now return the warning -321. This warning indicates that 
the data segment was opened successfully, but the file system returned a 
warning that the data within the segment may not be valid because the data 
segment was open when the system crashed. 
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OS ERROR MESSAGES 

The following list of OS error messages is in ascending numerical order. 
However, the ordering scheme ignores the sign of the error number; the 
minus sign preceding an error number indicates that the message is a 
warning; the OS may or may not have completed the flagged action. 

no error 

PROCESS MANAGEMENT 

100 Specified process does not exist 

101 Specified process is a system process 

110 Invalid priority specified (must be 1..255) (SetPriority_Process) 

-115 Specified process is already suspended ( Suspend_Proces s ) 

-120 Specified process is already active (Activate_Process) 

-125 Sepcified process is already terminating (KillJProcess) 

130 Could not open program file 

131 Error while trying to read program file 

132 Invalid program file (incorrect format) 

133 Could not get a stack segment for new process 

134 Could not get a syslocal segment for new process 

135 Could not get a PCB for new process (no sysglobal space) 

136 Could not set up communication channel for new process 

138 Error accessing program file while loading 

139 Could not get a PLCB to load the program (no sysglobal space) 

141 Error accessing a library file while loading program (e.g. the 
library file containing required shared segment not found) 

142 Can't run protected file on this machine 

143 Program uses an intrinsic unit not found in the Intrinsic 
Library 

144 Program uses an intrinsic unit whose name or type does not 
agree with the Intrinsic Library 

145 Program uses a shared segment not found in the Intrinsic 
Library 

146 Program uses a shared segment whose name does not agree with 
the Intrinsic Library 

147 No space in syslocal for program file descriptor during 
process creation 

148 No space in the shared IU data segment for shared IU globals 
required by the program 

EXCEPTION MANAGEMENT 

201 No such exception name declared 

202 No space left in the system data area for declare_execp_hdl 
or signal_excep. 

203 Null name specified as exception name. 
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MEMORY MANAGEMENT 

302 Invalid ldsn 

303 No data segment bound to an ldsn when there should be 

304 Data segment bound to an ldsn when it shouldn't be 

306 Data segment too large 

307 Input data segment path name is invalid 

308 Data segment already exists 

309 Insufficient disk space for data segment 

310 An invalid size has been specified: 

- memory size <= 

- memory size of shared data segment > 128K 

- disk size < 

311 Insufficient system resources 

312 Unexpected file system error 

313 Data segment not found 

314 Invalid address passed to Info__Ad dress 

315 Operation may cause a data lockout 

-320 Could not determine size of data segment. Defaults used 

were : memory size =512 bytes, disk size = bytes 

-321 Data segment open when the system crashed. Data possibly 
invalid. 



EVENT MANAGEMENT 

401 Invalid event channel name passed to make__event_chn: 
empty string or string longer than 16 characters 

402 No space left in system global data area for open_event__chn 

403 No space left in system local data area for open_event_chn 

404 Non-block structured device specified in pathname 

405 Catalog is full in Make_Event__Chn or Open__Event_Chn 

406 No such event channel exists in Kill_Event__Chn 

410 Attempt to open a local event channel to send 

411 Attempt to open an event channel to receive when event 
channel already has a receiver 

-412 Event channel was left open and system crashed, 

0penJEvent__Chn 
-413 Event channel was scavenged, 0pen_Event__Chn 
413 Unexpected file system error in Open_Event_Chn 

416 Cannot get enough disk space for event channel in 
0pen_Event_Chn 

417 Unexpected file system error in Close__Event_Chn 

420 Attempt to wait on a channel that the calling process 
did not open 

421 Wait__Event_Chn returns while waiting on an empty channel 
because a sender process was not able to successfully 
complete sending an event. 

422 Attempt to call wait_event_chn on an empty event-call 
channel 

423 Cannot find corresponding event channel after being 
b lo eked ( wa i t__e ve nt_chn ) 

424 The actual amount of data returned while reading an event 
from a channel is not the same as the size of that event 
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425 
426 
427 
428 

429 
430 

431 



432 
433 
440 
441 
445 
450 
600 



block in wait_event_chn (probably disk I/O failure) 

Event channel empty after being unblocked, Wait__Event__Chn 

Bad request pointer error returned in Wait_Event_Chn 

Wait_List has illegal length specified, Wait__Event_Chn 

Receiver unblocked because last sender closed, 

Wait_Event_Chn 

Unexpected file system error in Wait__Event_Chn 

Attempt to send to a channel which the calling process 

does not have open 

The actual amount of data transferred while writing an 

event to a channel is not the same as the size of an 

event block in send_event__chn (disk is probably full) 

Sender unblocked because receiver closed in Send__Event_Chn 

Unexpected file system error in Send_Event_Chn 

Unexpected file system error in Make__Event__Chn 

Event channel already exists in Make__Event_Chn 

Unexpected file system error in Kill_Event__Chn 

Unexpected file system error in Flush__Event__Chn 

See GENERAL I/O ERRORS below 



TWIGGY DISK 



606 
608 
609 
610 
614 
617 
618 



Can't find sector (disk unformatted) 

See GENERAL I/O ERRORS below 

See GENERAL I/O ERRORS below 

See GENERAL I/O ERRORS below 

No disk present in drive 

Checksum error 

Can't format, or write-protected 



GENERAL I/O 

600 Attempt to perform I/O operation on non I/O request 

605 Call to non-configured device driver 

608 Illegal length or disk address for transfer 

609 Call to non-configured device driver 

610 No more room in Sysglobal for I/O request 

615 Wrong call version to Twiggy 

616 Unpermitted Twiggy function 

619 No more room in Sysglobal for I/O request 

658 Premature end of file when reading from driver 

659 Corrupt file system header chain found in driver 

TIME MANAGEMENT 



630 



631 
634 
635 

636 
638 



The time passed to delay_time, convert__time, or 

send_event__chn is such that the year is less than 1900 

or greater than 2035. 

Illegal Timeout request parameter 

Illegal Timed event id of -1 

Process got unblocked prematurely due to process 

termination (delay_time) 

Timer request did not complete successfully (delay__time) 

The time passed to delay_time or send_event_chn is more 

than 23 days from the current GMT time 
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639 



RS-232 

640 
641 
642 
643 
646 
647 
648 
649 

PROFILE DISK 



Illegal date passed to Set_Time, or illegal date from 
system clock in Get Time 



RS-232 driver called with wrong version number 

RS-232 read or write initiated with illegal parameter 

Unimplemented or unsupported RS-232 driver function 

Unexpected RS-232 interrupt 

No memory available to initialize RS-232 

Unexpected RS-232 timer interrupt 

Attempt to send unpermitted command to serial controller card 

Illegal device control parameters to RS-232 



652 
653 
654 
655 
656 
658 
659 
660 
662 
663 
666 
670 
685 



N-port driver not initialized prior to Profile 

No room in sysglobal to initialize Profile 

Hard error status returned from drive 

Wrong call version to Profile 

Unpermitted Profile function 

See GENERAL I/O ERRORS above 

See GENERAL I/O ERRORS above 

Cable disconnected 

Parity error 

Checksum error 

Timeout 

Bad command response from drive 

Eject not allowed this device 



SERIAL DRIVER 

680 
682 
683 



Wrong call version to serial driver 

Unpermitted serial driver function 

No room in sysglobal to initialize serial driver 



N-PORT CARD DRIVER 



686 
687 
688 



No room in sysglobal to initialize n-port card driver 
Unpermitted n-port card driver function 
Wrong call version to n-port card driver 



PARALLEL PRINTER 



690 
691 
692 
693 
694 
696 
698 



Wrong call version to parallel printer 

Illegal parallel printer parameters 

N-port card not initialized prior to parallel printer 

No room in sysglobal to initialize parallel printer 

Unimplemented device control 

Out of paper 

Offline 
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STARTUP 



700 

701 
702 
703 
704 
705 
706 
707 
708 
709 
710 



Mismatch between loader version number (in OS. OBJ) and 

operating system version number (in SYSTEM. OS. OB J) 

OS exhausted its internal space during startup 

Cannot make system process 

Cannot kill pseudo-outer process 

Cannot create driver 

Cannot program NMI key 

Cannot (soft) initialize Twiggy 

Cannot (soft) initialize the file system volume 

Profile not readable 

Cannot map screen data 

Too many slot-based devices 



FILE SYSTEM 

VmStuff: 

801 IoResult <> on I/O using the Monitor (LISAIO) 

802 Asynchronous I/O request not completed successfully 

803 Bad combination of mode parameters (this is an internal 
error that should not occur when you run your code) 

806 Page specified is out of range (TFDM) 

809 Invalid arguments (page, address, offset, or count) (VM) 

810 The requested page could not be read in (VM) 

816 Not enough sysglobal space for file system buffers (initqvm) 

819 Bad device number (I0_INIT) 

820 No space in sysglobal for asynchronous request list 

821 Already initialized I/O for this device 

822 Bad device number (IO_DISINIT) 
SFilelO: 

825 Error in parameter values (Allocate) 

826 No more room to allocate pages on device 

828 Error in parameter values (Deallocate) 

829 Partial deallocation only (ran into unallocated region) 
835 s-file number < or > maxfiles (illegal value) (SList__I0) 

837 Unallocated s-file or I/O error (FMap__Mgr) 

838 Map overflow: s-file too large (this error obsolete from 
release 5.2 of the OS on) 

839 Attempt to compact file past PE0F (FMap_Mgr) 
841 Unallocated s-file or I/O error (Get_PSize) 

843 Requested exact fit, but one couldn't be provided (AppendPages) 

847 Requested transfer count is <= (DatalO) 

848 End-of-file encountered 

849 Invalid page or offset value in parameter list 
852 Bad unit number (FlushFS) 

854 No free slots in s-list directory (too many s-files) (New_SFile) 

855 No available disk space for file hints 

856 Device not mounted 

857 Empty, locked, or invalid s-file (Kill_SFile) 

861 Relative page is beyond PEOF (bad parameter value) (AbsPage) 

864 No sysglobal space for volume bitmap (Real_Mount, Real_Unmount ) 

866 Wrong FS version or not a valid Lisa FS volume 

867 Bad unit number (Real Mount, Real Unmount) 
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868 

869 

870 
FSJPrimitives 

871 

872 

873 

874 

875 

879 

881 

882 

883 

884 

885 

886 

887 

888 

890 

891 

892 

894 

895 

896 
FS Init: 

897 
FS_Interface: 

921 

922 

926 

927 

941 

946 

947 

948 

949 

950 

951 
952 
954 
955 
956 
957 
958 
959 
960 
961 
962 
963 
964 
965 
966 
967 



Bad unit number (Def_Mount, Def _Unmount ) 

Unit already mounted (mount )/no unit mounted (unmount) 

No sysglobal space for DCB or MDDF (mount) 

Parameter not a valid s-file ID (OpenJSFile) 

No sysglobal space for s-file control block 

Specified file is already open for private access 

Device not mounted 

Invalid s-file ID or s-file control block (Close_SFile) 

Attempt to post ion past LEOF (Direct_I0) 

Attempt to read empty file (FilelO) 

No space on volume for new data page of file 

Attempt to read past LEOF 

Not first auto-allocation, but file was empty 

Could not update filesize hints after a write (fileio) 

No syslocal space for I/O request list 

Catalog pointer does not indicate a catalog (bad parameter) 

Entry not found in catalog (Lookup_by_ename) 

Entry by that name already exists (Make_Entry) 

Catalog is full, or was not as catalog 

Illegal name for an entry 

Entry not found, or not a catalog (Kill_Entry) 

Invalid entry name (kill_entry) 

Safety switch is on — cannot kill entry (kill__entry) 

Invalid bootdev value 

Pathname invalid or no such device (Make__File) 

Invalid label size (Make_File) 

Pathname invalid or no such device (Make_Pipe) 

Invalid label size (Make__Pipe) 

Pathname invalid or no such device (Kill_0bject) 

Pathname invalid or no such device (Open) 

Not enough space in syslocal for file system refdb 

Entry not found in specified catalog (Open) 

Private access not allowed if file already open shared 

Pipe already in use, requested access not possible OR 

dwrite not allowed for pipe 

File is already opened in private mode (open) 

Bad refnum (Close__Object) 

Bad refnum (Read__data) 

Read access not allowed to specified object 

Attempt to position FMARK past LEOF not allowed 

Negative request count is illegal (read_data) 

Non-sequential access is not allowed (read_data) 

System resources exhausted 

Error writing to pipe while an unsatisfied read was pending 

Bad refnum (write_data) 

No WRITE or APPEND access allowed 

Attempt to position FMARK too far past LEOF 

Append access not allowed in absolute mode 

Append access not allowed in relative mode 

Internal inconsistency of FMARK and LEOF (warning) 

Non-sequential access is not allowed (write data) 



Calvert 



52 



July 23, 1982 



Confidential 



Guide to OS 



968 
971 
972 
974 
977 
978 
979 
981 
982 
983 
985 
986 
987 
988 
989 
990 
994 
995 
999 

1021 
1022 
1023 
1024 
1031 
1032 
1033 
1041 
1042 
1043 
1051 
1052 
1053 

-1063 



1061 
1062 
1071 
1091 
1092 
1121 
1128 
1130 
g e t_ope n__l i s t 
1131 
1132 
1133 

reg__open_lis t 
1134 
1135 



Bad refnum (Flush) 

Pathname invalid or no such device (Lookup) 

Entry not found in specified catalog 

Bad refnum (Info) 

Bad refnum (allocate) 

Page count is non-positive (allocate) 

Not a block structured device (allocate) 

Bad refnum (Truncate) 

No space has been allocated for specified file 

Not a block structured device (truncate) 

Bad refnum (Compact) 

No space has been allocated for specified file 

Not a block structured device (compact) 

Bad refnum (Flush_Pipe) 

Caller is not a reader of the pipe 

Not a block structured device (f lushjpipe) 

Invalid refnum (Set__File__Inf o) 

Not a block-structured device ( Set__File_JEnf o) 

Asynchronous read was unblocked before it was satisfied. 

This may occur during process termination. 

Pathname invalid or no such entry (Rename_Entry) 

No such entry found (rename__entry) 

Invalid newname, check for '-' in string (rename_entry) 

New name already exists in catalog (rename_entry) 

Pathname invalid or no such entry (Read_Label) 

Invalid transfer count (read__label) 

No such entry found (read__label) 

Pathname invalid or no such entry (Write__Label) 

Invalid transfer count (write__label) 

No such entry found (write__label) 

No device or volume by that name (mount) 

A volume is already mounted on device 

Attempt to mount the temporarily unmounted boot volume 

just unmounted from this machine (MOUNT) 

Warning, attempt to mount a temporarily unmounted boot 

volume that was either unmounted from another machine or 

was not the most recently unmounted boot volume. The 

mount is completed (MOUNT) 

No device or volume by that name (Unmount) 

No volume is mounted on device 

Not a valid or mounted volume for working directory 

Pathname invalid or no such entry (Set__Saf ety) 

No such entry found (set__safety) 

Invalid device, not mounted, or not a catalog (reset__catalog) 

Invalid pathname, device, or volume not mounted (get_dev__name) 

File is protected; cannot open due to protection violation 

No device or volume by that name 

No volume is mounted on that device 

No more open file& in the file list of that device 

(no files, data segments, event channels open on that device) 

Cannot find space in sysglobal for open file list 
Cannot find the open file entry to modify 
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fsjutilities calls: 

1136 Boot volume not mounted (fs_utility, ubd) 

1137 Boot volume already unmounted (fsjutility, ubd) 

1138 Caller cannot have higher priority than system 
processes when calling ubd (fsjutility, ubd) 

1141 Boot volume was not unmounted when calling rbd 

1142 Some other volume still mounted on the boot device when 
calling rbd 

1143 No sysglobal space for MDDF to do rbd 

1144 Attempt to remount a volume which is not the temporarily 
unmounted boot volume from the same machine (rbd) . 

1145 No sysglobal space for bit map to do rbd 

1159 fs__shutdown is not allowed while boot volume unmounted 
but operation is carried out 
fs_jshutdown calls: 

1158 Track-by-track copy buffer is too small 

1159 Shutdown requested while boot volume was unmounted 

1160 Destination device too small for track-by-track copy 

1161 Invalid final shutdown mode 

1162 Power is already off 
fsjutilities calls: 

1 163 Illegal command 

1164 Device is not a Twiggy device 

1165 No volume is mounted on the device 

1166 A valid volume is already mounted on the device 

1167 The Device is not blockstructured 

1 168 Device name is invalid 
newvolume (volume initialization): 

1169 Could not default mount volume before initialization 

1170 Could not mount volume after initialization 

1171 '-' is not allowed in a volume name 

1172 No space available to initialize a bitmap for the volume 

WARNINGS! from opening a file or mounting a volume: 
-1173 File was last closed by the OS 

-1174 File was left open or volume was left mounted, and system crashed 
-1175 File or volume was scavenged 

When these warnings occur on an OPEN call for a file or a MOUNT 
call for a volume, the OS goes ahead and opens the volume /file 
for access as usual. HOWEVER, the contents of the file might 
be inconsistent. 

CIRCULAR PIPES: 

1176 Cannot read from a pipe more than half of the allocated 
physical size (read_data) 

1177 Cannot cancel a read request for a pipe (read_data) 

1178 Process waiting in read_data for pipe data got unblocked 
because the last writer of the pipe has closed it (readjdata) 

1180 Cannot write to a pipe more than half of the allocated 
physical size (write_data) 

1181 No system space left for request block for pipe (write data) 
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1182 Writer process to a pipe got unblocked before the request 
was satisfied (this can occur during process termination) 
(write__data) 

1183 Cannot cancel a write request for a pipe (write_data) 

1184 Process waiting in write_data for pipe space got unblocked 
because the reader closed the pipe (write_data) 

1186 Cannot allocate space to a pipe while it has data wrapped 

around (allocate) 
1188 Cannot compact a pipe while it has data wrapped around 

(compact) 
1190 Attempt to access a page that is not allocated to the 

pipe (absrelbyte) 

OTHER: 

1196 Something is still open on device — cannot unmount (real_unmount ) 

1197 Volume is not formatted or cannot be read (def__mount) 

1198 Negative request count is illegal (write__data) 

1199 Function or procedure is not yet implemented 

1200 Illegal volume parameter 

1201 Blank file parameter 

1202 Error writing destination file 

1203 Invalid UCSD directory 

1204 File not found 

1210 Boot track program not executable 

1211 Boot track program too big 

1212 Error reading boot track program 

1213 Error writing boot track program 

1214 Source file not found 

1215 Can't write boot tracks on that device 

1216 Couldn't create/close internal buffer 

1217 Boot track program has too many code segments 

1218 Couldn't find configuration information entry 

1219 Couldn't get enough working space 

1220 Premature EOF in boot track program 

1221 Position out of range 

1222 No device at that position 

1998 Invalid parameter address 

1999 Bad refnum 

The pathname error codes (921, 926, 941, 946, and 971) often mean that the 
volume specified in the pathname is not mounted. If error 966 occurs 
while writing a file using the FTP utility, you probably ran out of space 
on the destination volume. 
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Operating System Error Codes by Procedure 



PROCESS MANAGEMENT 

Note that Yield CPU and Terminate Process return no errors 



Returned by all procedures except Make_Process 

100 Specified process does not exist 

101 Specified process is a system process 

Set Priori ty__Proces s 
110 - — * 



ocess 

Invalid priority specified (must be 1..255) 



Suspend Process 



-115 



Specified process is already suspended 



Act ivat e_Pr oces s 
-120 Specified process is already active 

Kill_Process 
-125 Specified process is already terminating 



Make_Process 
130 
131 
132 
133 
134 
135 
136 
138 
139 
141 



142 
143 



144 
145 
146 
147 
148 



Could not open program file 

Error while trying to read program file 

Invalid program file (incorrect format) 

Could not get a stack segment for new process 

Could not get a sys local segment for new process 

Could not get a PCB for new process (no sysglobal space) 

Could not set up communication channel for new process 

Error accessing program file while loading 

Could not get a PLCB to load the program (no sysglobal space) 

Error accessing a library file while loading program 

(e.g. library file containing shared segment required by 

program not found) 

Can't run protected file on this machine 

Program uses an intrinsic unit not found in the Intrinsic 

Library 

Program uses an intrinsic unit whose name or type does not 

agree with the Intrinsic Library 

Program uses a shared segment not found in the Intrinsic 

Library 

Program uses a shared segment whose name does not agree 

with the Intrinsic Library 

No space in syslocal for program file descriptor during 

process creation 

No space in the shared IU data segment for shared IU 

globals required by the program 
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EXCEPTION MANAGEMENT 



Returned by all procedures 

1998 Invalid parameter address 

Declare_excep__hdl 

201 No such exception name declared 

202 No space left in the system data area 

203 Null name specified as exception name. 

Disable_excep 

201 No such exception name declared 

203 Null name specified as exception name. 

Enable_excep 

201 No such exception name declared 

203 Null name specified as exception name. 

Inf o_excep 

201 No such exception name declared 

203 Null name specified as exception name. 

Flush_excep 

201 No such exception name declared 

203 Null name specified as exception name. 

Signal__excep 

201 No such exception name declared 

202 No space left in the system data area 

203 Null name specified as exception name. 



MEMORY MANAGEMENT 

Returned by all procedures 

1998 Invalid parameter address 

Returned by all procedures except INF0__LDSN, MAKEJDATASEG, OPENJDATASEG, 
KILLJDATASEG, and MEM_INF0 

1999 Bad refnum 

Note that SETACCESSJDATASEG and INFOJDATASEG return only 1998 and 1999 
and that MEM_INF0 returns only 1998 

INF0_LDSN 

302 Invalid ldsn 

303 No data segment bound to an ldsn when there should be 

UNBIND_DATASEG 

303 No data segment bound to an ldsn when there should be 

BINDJDATASEG 

302 Invalid ldsn 

304 Data segment bound to an ldsn when it shouldn't be 
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MAKE_DATASEG 

302 Invalid ldsn 

304 Data segment bound to an ldsn when it shouldn't be 

306 Data segment too large 

307 Input data segment path name is invalid 

308 Data segment already exists 

309 Insufficient disk space for data segment 

310 An invalid size has been specified: 

- memory size <- 

- disk size < 

311 Insufficient system resources 

312 Unexpected file system error 
315 Possible data lockout 

0PEN_DATASEG 

302 Invalid ldsn 

304 Data segment bound to an ldsn when it shouldn't be 

306 Data segment too large 

307 Input data segment path name is invalid 

311 Insufficient system resources 

312 Unexpected file system error 

313 Data segment not found 
315 Possible data lockout 

-320 Warning: could not determine size of data segment. 
The following defaults were used: 

- memory size =512 bytes 

- disk size = bytes 

-321 Data segment open when system crashed 

CLOSEJDATASEG 

312 Unexpected file system error 

KILL_DATASEG 

307 Input data segment path name is invalid 

312 Unexpected file system error 

313 Data segment not found 

SIZEJ)ATASEG 

304 Data segment being grown into an LDSN already in use 
306 Data segment too large 

309 Insufficient disk space for data segment 

310 An invalid size has been specified: 

- memory size <= 

- memory size of shared data segment > 128K 

- disk size < 

312 Unexpected file system error 

315 Possible data lockout 

FLUSH_DATASEG 

312 Unexpected file system error 

INF0_ADDRESS 

303 No data segment bound to the address 

314 Address does not fall within valid ldsn range 
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EVENT MANAGEMENT 

Returned by all procedures 

1998 Invalid parameter address 

Make__E ve nt_Chn 

401 Invalid event channel name passed to Make_Event_Chn : 
empty string or string longer than 16 characters 

404 Non-block structured device specified in pathname to 
Make__Event_Chn , Kill_Event_Chn, or Open__Event_Chn 

405 Catalog is full in Make_Event_Chn 

440 Unexpected file system error in Make__Event__Chn 

441 Event channel already exists in Make_Event__Chn 

Kil l_Event_Chn 

401 Invalid event channel name passed to Kill_Event_Chn: 

empty string or string too long 
404 Non-block structured device specified in pathname 

406 No such event channel exists in Kill___Event_Chn 
445 Unexpected file system error in Kill_Event__Chn 

Open_Event_Chn 

201 No such exception name declared 

401 Invalid event channel name passed to OpenJEvent_Chn: 
empty string or string too long 

402 No space left in system global data area for Open__Event__Chn 

403 No space left in system local data area for 0pen_Event__Chn 

404 Non-block structured device specified in pathname 
406 No such event channel exists in 0pen_Event_Chn 

411 Attempt to open an event channel to receive when event 
channel already has a receiver 
-412 Event channel was left open and system crashed, 

Ope n_Event__Chn 
-413 Event channel was scavenged, Open__Event_Chn 
413 Unexpected file system error in 0pen_Event_Chn 

416 Cannot get enough disk space for event channel at open 
Returned when the event channel is local: 

405 Catalog is full in 0pen_Event__Chn 

410 Attempt to open a local event channel to send 

Close__Event__Chn 

201 No such exception name declared 

417 Unexpected file system error in Close__Event__Chn 

1999 Bad refnum 

Inf o_E ve nt_Chn 
1999 Bad refnum 
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Wait_JEvent 
402 
420 

421 



422 
423 
424 



425 
426 
427 
428 
429 
1999 



Chn 



No space left in system global data area 

Attempt to wait on a channel that the calling process 

did not open 

Wait_Event Chn returns while waiting on an empty channel 

because a sender process was not able to successfully 

complete sending an event 

Attempt to call Wait_Event__Chn on an empty event-call channel 

Cannot find corresponding event channel after being blocked 

The actual amount of data returned while reading an event 

from a channel is not the same as the size of an event 

block in WaitJEvent_Chn (probably disk I/O failure) 

Event channel empty after being unblocked 

Bad request pointer error return from Can_Aread_Pipe 

Wait_List has illegal length specified, Wait_Event_Chn 

Receiver unblocked because last sender closed, Wait_Event_Chn 

Unexpected file system error in Wait___Event_Chn 

Bad refnum 



Flus h__Event__Chn 

450 Unexpected file system error in Flush_Event__Chn 
1999 Bad refnum 



Send Event Chn 



430 
431 



432 

433 

1999 



Attempt to send to a channel which the calling process 
does not have open 

The actual amount of data transferred while writing an 
event to a channel is not the same as the size of an 
event block in Send_Event__Chn (disk is probably full) 
Sender unblocked because receiver closed in Send__Event_Chn 
Unexpected file system error in Send_Event__Chn 
Bad refnum 



TIME MANAGEMENT 

Returned by all procedures : 
(Note that this is the only error message that Set_Local__Time_Dif f 
returns ) 
1998 Invalid parameter address 



Delay_Time 
630 



632 
635 



636 
638 



The time passed to Delay_Time, Convert__Time, or 

Send__Event___Chn is such that the year is less than 1900 

or greater than 2035 

No space in sysglobal 

Process got unblocked prematurely due to process 

termination ( DelayJTime ) 

Timer request did not complete successfully 

The time passed to DelayJTime or Send_Event_Chn is more 

than 23 days from the current GMT time 
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Convert__Time 

630 The time passed to DelayJTime, Convert__Time , or 

Send Event__Chn is such that the year is less than 1900 
or greater than 2035 

GetJTime 

639 Year not between 1981 and 1995 in GetJTime or Set__time. 
In Get_Time the error indicates a dead battery. 

SetJTime 

639 Year not between 1981 and 1995 in Get Time or Set Time. 



PWBT 
1210 
1211 
1212 
1213 
1214 
1215 
1216 
1217 
1218 
1219 
1220 



Boot track program not executable 

Boot track program too big 

Error reading boot track program 

Error writing boot track program 

Source file not found 

Can't write boot tracks on that device 

Couldn't create/close internal buffer 

Boot track program has too many code segments 

Couldn't find configuration information entry 

Couldn't get enough working space 

Premature EOF in boot track program 



PFTP 
1200 
1201 
1202 
1203 
1204 



Illegal volume parameter 

Blank file parameter 

Error writing destination file 

Invalid UCSD directory 

File not found 



Ge t Conf i g__Name 

1221 Position out of range 

1222 No device at that position 



DiskJLikely 
1221 
1222 



Position out of range 

No device at that position 
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OS LOADER DIAGNOSTICS 
Error Message 
FILE SYSTEM VERSION MISMATCH 

FILE SYSTEM CORRUPT 

MEMORY EXHAUST 

SYSTEM CODE FILE NOT FOUND 

SYSTEM CONFIGURATION FILE 
NOT FOUND 

BOOT DEVICE READ FAILED 

CODE FILE CORRUPT 
TOO MANY OS SEGMENTS 
SYSTEM DEBUG FILE NOT FOUND 
PROGRAM NOT EXECUTABLE 

SYSTEM LOW LEVEL DRIVER FILE 
NOT FOUND 

CONFIGURATION FILE NOT USABLE 

WRONG DRIVER 



RANGE ERROR, OR UNKNOWN BOOT 
ERROR 



Cause or Description 

The boot tracks don't know 
the right file system version 

Either damaged file system or 
damaged contents 

The OS will not fit 

Cannot find SYSTEM. OS 

Cannot find SYSTEM. CONFIG 

Device could not be read for 
whatever reason 

Refers to SYSTEM. OS 

Refers to SYSTEM. OS 

Cannot find SYSTEM. DEBUG 

Refers to SYSTEM. OS, SYSTEM. DEBUG 
or SYSTEM. LLD 

Refers to SYSTEM. LLD 

Refers to SYSTEM. CONFIG 

For instance, storing a 
Twiggy driver on a Profile 

A loader bug 
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SYSTEM ERRORS 

A system error indicates that something has gone seriously awry within the 
Operating System code. When a system error occurs, the Operating System 
reports the error and stops. Please report the occurrence of any system 
errors to the Operating System group. 

Common system errors: 

10102 Error while creating System. Shell during StartUp 

10201 Hardware exception (divide by zero, for example) 

in Operating System code 



EXCEPTIONS 

During execution applications can field hardware exceptions. If such an 
exception occurs, the system displays one of the following messages: 

Bus error or address error exception: 

EXCEPTION in process of gid <gggg> 

Process is about to be terminated. 

access address = <aaaaaaaa> = mmu# <mmm> (segment name), offset <oooo> 

inst reg = <rrrr> sr = <ssss> pc = <PPPPPP> 

saved registers at <xxxxxxxx> 

Going to Lisabug, type g to continue 

Any other hardware exception: 

EXCEPTION in process of gid <gggg> 
Process is about to be terminated, 
sr = <ssss> pc = <pppppp> 
saved registers at <xxxxxxxx> 
Going to Lisabug, type g to continue 

whe re : 

<gggg> is tne global ID of the process that incurred the exception. 
<aaaaaaaa> is the address that caused the bus or address error 
<mmm> is the segment number represented by <aaaaaaaa> and 
<oooo> is the offset within that segment 

<rrrr> is the value of the instruction register at the time of the exception 
<ssss> is the value of the status register at the time of the exception 
<pppppp> is the value of the program counter at the time of the exception 
<xxxxxxxx> is the address of the saved register information 

All numbers displayed are decimal; the segment name is displayed only if 
the segment number makes sense to the Operating System. 
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If the exception is divide by zero, overflow, or CHK out of bounds, the 
process is not terminated and the line to that effect is not shown. If 
the process has declared an exception handler for this exception, that 
handler is entered after you type g to LisaBug, and the process then 
continues execution. If no handler has been declared, the system default 
handler terminates the process. If the exception is a bus error and the 
segment name is 'stack seg', a stack overflow has probably occurred. The 
Operating System cannot currently recover from this error. 

If the exception occurs in Operating System code, the displays are the same 
as given above except that the first two lines are replaced by: 

EXCEPTION in system code! 

If you type g in Lisabug after this exception, a system error 10201 occurs 
and you must reboot. 

You should use release 7.4 or later of the Monitor because in these 
versions the Lisabug register display is the user's register display and 
the user can use the stack crawl command to find the calling procedures. 
You should not examine the memory location <xxxxxx> that contains the 
saved registers because the debugger saves the system's registers there. 
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